Skip to main content

​
Overview

Cross-ramp transactions convert one fiat currency into another without the user needing to interact with cryptocurrency. Capa handles the conversion internally and delivers the target currency to the specified bank account. Supported currencies: MXN (Mexican Peso), DOP (Dominican Peso), USD (US Dollar), and EUR (Euro). The source and target currencies must differ.

​
Integration Flow

1

Create a user and complete KYC

Create User, then KYC verification
2

Get a cross-ramp quote (optional)

Create Cross-Ramp Quote to lock the exchange rate
3

Create cross-ramp transaction

Create Cross-Ramp
4

User deposits source currency

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

​
How to do a Cross-Ramp Operation

To successfully execute a cross-ramp operation, follow these steps:

  1. ​
    Select Source and Target Currencies:

    Choose the fiat currencies for the conversion. For example, MXN to USD or EUR to MXN. The source and target currencies must be different.

  2. ​
    Quoting:

    1. To show a real-time estimate of how much the user will receive, use the Get Cross-Ramp Quote Rate endpoint with sourceCurrency, targetCurrency, and either sourceAmount or targetAmount.
    2. To lock a guaranteed exchange rate, use the Create Cross-Ramp Quote endpoint. This returns a quoteId with an expiration time (expiresAt). Pass the quoteId when creating the transaction to use the locked rate.
    3. You can specify either sourceAmount or targetAmount, not both.

  3. ​
    Target Bank Account:

    Provide the bank account where the target currency will be delivered. You can either:
    • Pass targetBankAccount inline in the request body with the bank details.
    • Use a previously saved bank account ID (targetBankAccountId).
    Bank account requirements vary by country:
    CountryRequired Fields
    MXaccountIdentifier (18-digit CLABE)
    DOaccountIdentifier, bankName, accountType, documentIdentifier, documentType
    USaccountIdentifier, bankName, routingNumber (9-digit ABA), accountHolder (type, firstName/lastName or businessName), address (streetLine1, city, postalCode, country)
    SEPAiban, bic, bankName, accountHolder (type, firstName/lastName or businessName)
    The targetCurrency must match the currency of the target bank account’s country.

  4. ​
    Create the Cross-Ramp Transaction:

    With all required information gathered, create the transaction using the Create Cross-Ramp endpoint. Key parameters:
    • userId (required): The user’s Capa ID
    • sourceCurrency (required): The fiat currency the user will deposit
    • targetCurrency (required): The fiat currency to be delivered
    • sourceAmount or targetAmount: The amount to convert (provide one, not both)
    • targetBankAccount: Inline bank account details for the target
    • quoteId (optional): A locked quote ID from the Create Cross-Ramp Quote endpoint
    • premiumSpread (optional): A spread percentage to apply to the exchange rate
    • receiverId (optional): A previously created receiver for third-party payouts (see Receivers Guide)

  5. ​
    User Deposits Source Currency:

    After the transaction is created, the response includes sourceBankAccount with the bank details where the user must deposit the source fiat currency. Share this information with the user so they can complete the deposit.

​
Transaction Limits

The same minimum amounts apply as for on-ramp and off-ramp transactions:
CurrencyMinimumMaximum
MXN50 MXNNo maximum
DOP150 DOPNo maximum
USD20 USDNo maximum
EUR20 EURNo maximum

​
Funding a Cross-Ramp

After creating the transaction, the response includes sourceBankAccount with the bank details where the user must deposit the source fiat currency. The transaction starts in PENDING_FUNDS status.
  • For MXN source: The user deposits via SPEI to Capa’s bank account (same flow as on-ramp).
  • For non-MXN source (USD, EUR, DOP): A deposit intent is created with instructions for the user to include in their transfer.
The source fiat deposit must be made after the cross-ramp transaction is created. The deposit is matched to the cross-ramp order internally — there is no concepto/reference matching mechanism for cross-ramps.

​
Multiple Concurrent Orders

You can have multiple cross-ramp transactions open at the same time for a single user.

​
Quoting and Premium Spread

When using premiumSpread, note that if a quoteId is provided in the cross-ramp request, the quote’s premiumSpread is used and any premiumSpread value in the request body is ignored. To ensure consistent pricing, always set premiumSpread when creating the quote. The valid range is 0 to 1. A locked quote is valid for 10 seconds after creation (expiresAt field in the response). Once the quote is used to create a transaction, the rate is locked for that transaction. A quote is optional — if no quoteId is provided, provide sourceAmount or targetAmount along with sourceCurrency and targetCurrency. You cannot specify both sourceAmount and targetAmount.
When using quoteId, do not pass sourceAmount, targetAmount, sourceCurrency, or targetCurrency — these values are taken from the quote.

​
Transaction Status Progression

StatusDescription
PENDING_FUNDSTransaction created, waiting for the user to deposit source fiat
FUNDS_RECEIVEDSource fiat has been received
IN_PROGRESSConversion is being processed
AWAITING_FUND_TRANSFERConversion complete, awaiting delivery to target bank account
COMPLETEDTarget fiat has been delivered to the bank account
CANCELLEDTransaction was cancelled (can occur at PENDING_FUNDS stage)

​
Notifications

Capa sends webhook notifications for each status change. The following events are emitted during a cross-ramp transaction lifecycle:
EventTriggered When
CREATED_CROSS_RAMPTransaction created
FUNDS_RECEIVED_CROSS_RAMPSource fiat received
STARTED_PROCESSING_CROSS_RAMPConversion processing begins
AWAITING_FUND_TRANSFER_CROSS_RAMPAwaiting delivery to target bank
COMPLETED_CROSS_RAMPTarget fiat delivered
CANCELLED_CROSS_RAMPTransaction cancelled
See the Transaction Events guide for full payload examples. Ensure your Webhook Settings are configured to receive these notifications.

​
What’s Next