/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 '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "targetBankAccount": {
    "accountIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "accountHolder": {
      "businessName": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "address": {
      "streetLine1": "<string>",
      "streetLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "US"
    }
  },
  "sourceAmount": 123,
  "targetAmount": 123,
  "quoteId": "<string>",
  "premiumSpread": 123
}
'

{
  "success": true,
  "data": {
    "id": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "status": "PENDING",
    "exchangeRate": 0.95,
    "sourceBankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "isVerified": true,
      "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",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "targetBankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "isVerified": true,
      "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",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "createdAt": "2024-01-01T12:00:00Z",
    "sourceCurrency": "MXN",
    "targetCurrency": "DOP",
    "sourceAmount": 1000,
    "targetAmount": 950,
    "premiumSpread": 0.01,
    "completedAt": "<string>"
  }
}

POST

api

partner

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 '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "targetBankAccount": {
    "accountIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "accountHolder": {
      "businessName": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "address": {
      "streetLine1": "<string>",
      "streetLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "US"
    }
  },
  "sourceAmount": 123,
  "targetAmount": 123,
  "quoteId": "<string>",
  "premiumSpread": 123
}
'

{
  "success": true,
  "data": {
    "id": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "status": "PENDING",
    "exchangeRate": 0.95,
    "sourceBankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "isVerified": true,
      "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",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "targetBankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "isVerified": true,
      "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",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000"
    },
    "createdAt": "2024-01-01T12:00:00Z",
    "sourceCurrency": "MXN",
    "targetCurrency": "DOP",
    "sourceAmount": 1000,
    "targetAmount": 950,
    "premiumSpread": 0.01,
    "completedAt": "<string>"
  }
}

Creates a cross-ramp transaction on behalf of a verified user. This converts one fiat currency to another (e.g., MXN to USD) and initiates the transfer to the target bank account.

For staging transaction testing, use the Mock Testing Guide.

Field Relationships

Provide either sourceAmount or targetAmount, not both.
Provide either targetBankAccount (inline bank details) or targetBankAccountId (reference to a saved bank account).
sourceCurrency and targetCurrency must differ.
targetCurrency must match the currency of the target bank account’s country.
receiverId is optional — when provided, the transaction is processed for that receiver.

Bank Account Requirements by Country

Country	Required Fields
MX	`accountIdentifier` (18-digit CLABE)
DO	`accountIdentifier`, `bankName`, `accountType`, `documentIdentifier`, `documentType`
US	`accountIdentifier`, `bankName`, `routingNumber`, `accountHolder`, `address`
SEPA	`iban`, `bic`, `bankName`, `accountHolder`

Integration Flow

Create a user and complete KYC

POST /api/partner/v2/users, then KYC verification

Get a cross-ramp quote (optional)

POST /api/partner/v2/cross-ramp/quotes — locks the exchange rate

Create cross-ramp transaction

POST /api/partner/v2/cross-ramp (this endpoint)

User deposits source currency

The user deposits fiat in the source currency to the bank account in sourceBankAccount.

Important Notes

User must be KYC-verified before creating transactions.
Supported corridors: MX, DO, US, and SEPA countries.
Amount limits: Fiat amounts must fall within the min/max thresholds defined in your partner agreement.

Use Cases

International Remittances: Convert MXN to USD and send funds to a US bank account.
Multi-Currency Payouts: Deliver funds in a different fiat currency from the source deposit.
Cross-Border B2B Payments: Facilitate business payments across currencies.

Error Codes

Common Errors

HTTP Status	Code	Message
401	`UNAUTHORIZED`	”API Key is missing”
401	`UNAUTHORIZED`	”Invalid API Key format”
401	`UNAUTHORIZED`	”Invalid API Key”
403	`INVALID_PARTNER_FLOW`	”The partner has an invalid flow.”

Verified User Errors

HTTP Status	Code	Message
400	`REQUIRED_USER_ID_ERROR`	”This endpoint requires a user id to be provided”
403	`USER_NOT_VERIFIED_ERROR`	”User is not allowed to perform the operations because has not completed the KYC verification.”

Endpoint-Specific Errors

HTTP Status	Code	Message
400	`INVALID_USER_INPUT_ERROR`	”Invalid User Input”
400	`BAD_REQUEST`	”Either targetBankAccount or targetBankAccountId must be provided”
400	`BAD_REQUEST`	”Unsupported country for cross-ramp: “
400	`BAD_REQUEST`	”Target currency must match target bank account currency (expected: , actual: )“
400	`BAD_REQUEST`	”Source and target currencies must differ”
400	`BAD_REQUEST`	”Requested fiat currency is invalid or inactive”
400	`BAD_REQUEST`	”Provided quoteId is not a CROSS_RAMP quote”
400	`BAD_REQUEST`	”Quote currency mismatch (expected: , actual: )“
400	`QUOTE_EXPIRED`	”Quote has expired”
400	`BAD_REQUEST`	”Cannot create transaction: No supported banks configured for user with id: “
400	`BAD_REQUEST`	”The receiver user account is not verified”
403	`RECEIVER_CANNOT_INITIATE_TRANSACTION`	”Receiver accounts cannot initiate transactions directly.”
403	`RECEIVER_USER_MISMATCH`	”The receiver does not belong to the specified user.”
403	`USER_BANK_INFO_ACCESS_DENIED`	”The bank information does not belong to the specified user.”
404	`RECEIVER_NOT_FOUND`	”Receiver not found.”
404	`USER_BANK_INFO_NOT_FOUND`	”User bank information not found.”

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

Show child attributes

sourceAmount

number

Amount of currency from source

targetAmount

number

Amount of currency that will be delivered

quoteId

string

Identifier for the quote to be used for the transaction.

premiumSpread

number

Premium spread percentage

Response

201 - application/json

success

boolean

Example:

true

data

object

Show child attributes

/api/partner/v2/off-ramp/execute /api/partner/v2/cross-ramp/quotes

⌘I

​Field Relationships

​Bank Account Requirements by Country

​Integration Flow

​Important Notes

​Use Cases

​Error Codes

​Common Errors

​Verified User Errors

​Endpoint-Specific Errors

Headers

Body

Response

Field Relationships

Bank Account Requirements by Country

Integration Flow

Important Notes

Use Cases

Error Codes

Common Errors

Verified User Errors

Endpoint-Specific Errors