post https://staging-api.capa.fi/api/partner/v2/cross-ramp
Creates a cross-ramp transaction on behalf of a verified user. This enables the conversion of fiat to fiat and initiates the transfer to the target bank account.
🔐 Headers
| Header | Description |
|---|---|
partner-api-key | API key associated with your partner account. Required. See API Key Generation Guide. |
This endpoint requires authentication using a valid
partner-api-key.
For Staging Transaction Testing please use Mock Testing Guide
📥 Request Body
Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | ✅ | ID of the user on whose behalf the transaction is created. The user's kyc must be verified first. |
sourceAmount | number | 🔘 | Amount of fiat to be converted. Required if cryptoAmount is not provided. |
targetAmount | number | 🔘 | Amount of crypto to be converted to fiat. Required if fiatAmount is not provided. |
sourceCurrency | string | ✅ | Currency to send for the cross-ramp transaction. The user must have an account in this currency. Accepted values follow the ISO 4217 format (e.g., MXN, DOP,USD). |
premiumSpread | number | 🔘 | Additional percentage applied to the exchange rate. This amount is fully awarded to the partner. |
userBankInformation | object | ✅ | User's bank information to be saved. See nested fields below. |
userBankInformation .accountIdentifier | string | ✅ | Unique account identifier (CLABE for Mexico, Account Number for the Dominican Republic). |
userBankInformation .country | string | ✅ | Country in which the bank account is held. |
userBankInformation .bankName | string | 🔘 | Name of the user's bank. List of Dominican Republic Banks |
userBankInformation .accountType | string | 🔘 | Type of bank account SAVINGS or CHECKING. Only required for the Dominican Republic. |
userBankInformation .documentIdentifier | string | 🔘 | Unique identifier of the document linked to the bank account. Only required for the Dominican Republic. |
userBankInformation .documentType | string | 🔘 | Document Type PASSPORT or RNC orCEDULA. Only Required for the Dominican Republic |
📨 Example Request
curl --request POST \
--url https://staging-api.capa.fi/api/partner/v2/on-ramp \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'partner-api-key: API-KEY' \
--data '
{
"sourceCurrency": "USD",
"userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
"sourceAmount": 10000,
"targetAmount": 10000,
"userBankInformation": {
"accountIdentifier": "012345678912345678",
"country": "MX"
},
"premiumSpread": 0.01
}
'
📤 Response Body
| Field | Type | Description |
|---|---|---|
id | string | Unique ID of the created transaction. |
userId | string | User ID associated with the transaction. |
status | string | Current status of the transaction. Initially set to "PENDING". |
cryptoAmount | number | Amount of cryptocurrency being converted. |
fiatAmount | number | Amount of fiat currency received after conversion. |
exchangeRate | number | Exchange rate used for the crypto-to-fiat conversion. |
tokenSymbol | string | Symbol of the cryptocurrency used. |
blockchainSymbol | string | Symbol of the blockchain the cryptocurrency belongs to. |
fiatCurrency | string | Currency code of the fiat currency received (e.g., "MXN"). |
createdAt | string | ISO timestamp indicating when the transaction was created. |
completedAt | string | ISO timestamp indicating when the transaction was completed, or null if pending. |
userBankInformation | object | User's bank information. See nested fields below. |
userBankInformation .accountIdentifier | string | Unique account identifier (CLABE for Mexico, Account Number for the Dominican Republic). |
userBankInformation .country | string | Country in which the bank account is held. |
userBankInformation .bankName | string | Name of the user's bank. List of Dominican Republic Banks |
userBankInformation .accountType | string | Type of bank account SAVINGS or CHECKING. Only required for the Dominican Republic. |
userBankInformation .documentIdentifier | string | Unique identifier of the document linked to the bank account. Only required for the Dominican Republic. |
userBankInformation .documentType | string | Document Type PASSPORT or RNC orCEDULA. Only Required for the Dominican Republic |
bankAccount | object | Information about the user's bank account. |
bankAccount .isVerified | boolean | Indicates whether the account has been verified and linked to the user. |
bankAccount .accountIdentifier | string | Unique identifier of the account (CLABE for Mexico, Account Number for DO). |
bankAccount .country | string | Country where the bank account is held. |
bankAccount .accountType | string | Type of bank account. Only required for the Dominican Republic. |
bankAccount .bankName | string | Name of the bank. Only required for the Dominican Republic. |
bankAccount .documentIdentifier | string | Unique identifier of the document linked to the account. |
premiumSpread | number | Additional percentage applied for premium services. |
📘 Example Response
{
"success": true,
"data": {
"id": "0483907e-ca31-432c-8234-fc401a921ef9",
"userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
"status": "PENDING",
"sourceAmount": 0.26,
"targetAmount": 4.728013,
"exchangeRate": 18.184665,
"sourceCurrency": "DOP",
"targetCurrency": "MXN",
"createdAt": "2025-06-09T21:51:32.288Z",
"completedAt": null,
"userBankInformation": {
"country": "MX",
"accountIdentifier": "012345678902422382",
"isVerified": true
},
"bankAccount": {
"country": "DO",
"bankName":"Banco BHD",
"accountIdentifier": "012345678902422382",
"isVerified": true
},
"premiumSpread": 0.005
}
}
⚠️ Important Notes & Requirements
- Partner API Key is mandatory: All requests must include a valid
PartnerApiKeyin the header. Get your API key. - User must be verified: The user (
userId) must have completed KYC and have an will go through an account verification process. The verification is only made once. - Supported Countries: Only flows from
MX(Mexico),DO(Dominican Republic) andUS(United States) are currently supported. - Amount Limits: Crypto amounts must respect the minimum and maximum thresholds defined in the partner agreement.
✅ Use Cases
- User Payout: Initiate a crypto-to-fiat payout to a verified user.
- B2C Integration: Allow individual users to off-ramp from within your app or service.
- B2B or Corporate Flows: Automate withdrawals to company bank accounts after receiving crypto payments.