Skip to main content
POST
/
api
/
partner
/
v2
/
cross-ramp
cURL
curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/cross-ramp \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --data '{
  "targetBankAccount": {
    "accountIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "country": "MX",
    "accountType": "SAVINGS",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "documentType": "PASSPORT",
    "accountHolder": {
      "type": "INDIVIDUAL",
      "businessName": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "address": {
      "streetLine1": "<string>",
      "streetLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "US"
    }
  },
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceAmount": 1000,
  "targetAmount": 50.5,
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "quoteId": "<string>",
  "premiumSpread": 0.01
}'
{
  "success": true,
  "data": {
    "id": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "status": "PENDING",
    "sourceCurrency": "MXN",
    "targetCurrency": "DOP",
    "sourceAmount": 1000,
    "targetAmount": 950,
    "exchangeRate": 0.95,
    "sourceBankAccount": {
      "accountHolder": {
        "type": "BUSINESS",
        "name": "Capa.fi"
      },
      "bic": "DEUTDEFF",
      "routingNumber": "021000021",
      "address": {
        "streetLine1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "message": "RANDOM_MESSAGE",
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "isVerified": true,
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "targetBankAccount": {
      "accountHolder": {
        "type": "BUSINESS",
        "name": "Capa.fi"
      },
      "bic": "DEUTDEFF",
      "routingNumber": "021000021",
      "address": {
        "streetLine1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "message": "RANDOM_MESSAGE",
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "isVerified": true,
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "createdAt": "null",
    "premiumSpread": 0.01,
    "completedAt": "<string>"
  }
}
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

HeaderDescription
partner-api-keyAPI 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

ParameterTypeRequiredDescription
userIdstring✅ID of the user on whose behalf the transaction is created.
The user’s kyc must be verified first.
sourceAmountnumber🔘Amount of fiat to be converted. Required if cryptoAmount is not provided.
targetAmountnumber🔘Amount of crypto to be converted to fiat. Required if fiatAmount is not provided.
sourceCurrencystring✅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).
premiumSpreadnumber🔘Additional percentage applied to the exchange rate. This amount is fully awarded to the partner.
userBankInformationobject✅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
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

FieldTypeDescription
idstringUnique ID of the created transaction.
userIdstringUser ID associated with the transaction.
statusstringCurrent status of the transaction. Initially set to "PENDING".
cryptoAmountnumberAmount of cryptocurrency being converted.
fiatAmountnumberAmount of fiat currency received after conversion.
exchangeRatenumberExchange rate used for the crypto-to-fiat conversion.
tokenSymbolstringSymbol of the cryptocurrency used.
blockchainSymbolstringSymbol of the blockchain the cryptocurrency belongs to.
fiatCurrencystringCurrency code of the fiat currency received (e.g., "MXN").
createdAtstringISO timestamp indicating when the transaction was created.
completedAtstringISO timestamp indicating when the transaction was completed, or null if pending.
userBankInformationobjectUser’s bank information. See nested fields below.
userBankInformation .accountIdentifierstringUnique account identifier (CLABE for Mexico, Account Number for the Dominican Republic).
userBankInformation .countrystringCountry in which the bank account is held.
userBankInformation .bankNamestringName of the user’s bank. List of Dominican Republic Banks
userBankInformation .accountTypestringType of bank account SAVINGS or CHECKING. Only required for the Dominican Republic.
userBankInformation .documentIdentifierstringUnique identifier of the document linked to the bank account. Only required for the Dominican Republic.
userBankInformation .documentTypestringDocument Type PASSPORT or RNC orCEDULA. Only Required for the Dominican Republic
bankAccountobjectInformation about the user’s bank account.
bankAccount .isVerifiedbooleanIndicates whether the account has been verified and linked to the user.
bankAccount .accountIdentifierstringUnique identifier of the account (CLABE for Mexico, Account Number for DO).
bankAccount .countrystringCountry where the bank account is held.
bankAccount .accountTypestringType of bank account. Only required for the Dominican Republic.
bankAccount .bankNamestringName of the bank. Only required for the Dominican Republic.
bankAccount .documentIdentifierstringUnique identifier of the document linked to the account.
premiumSpreadnumberAdditional 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 PartnerApiKey in 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) and US (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.

Headers

​
partner-api-key
string
required

Api key for the affiliated partner that is performing the request

Body

application/json
​
userId
string
required

User's identifier

Example:

"12a121ad-cbea-4ec4-9e0a-5c861e528bba"

​
sourceCurrency
enum<string>
required

Source currency symbol

Available options:
MXN,
DOP,
USD,
EUR
Example:

"MXN"

​
targetCurrency
enum<string>
required

Target currency symbol

Available options:
MXN,
DOP,
USD,
EUR
Example:

"USD"

​
targetBankAccount
object

User bank info to be saved

​
sourceAmount
number

Amount of currency from source

Example:

1000

​
targetAmount
number

Amount of currency that will be delivered

Example:

50.5

​
quoteId
string

Identifier for the quote to be used for the transaction.

​
premiumSpread
number

Premium spread percentage

Example:

0.01

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object