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. USD can also be delivered to bank accounts in China (CN) and Hong Kong (HK) as destination-only corridors. See China & Hong Kong destinations for the additional requirements.

​
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: 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)
    • reference (optional): A free-form reference string for your own records (max 140 characters)
    • targetCountry (optional): Target country override — required to deliver USD to China (CN) or Hong Kong (HK) (see below)
    • targetRail (optional): Target payment rail for CN/HK — LOCAL (default) or SWIFT
    • invoiceFile (optional): Base64-encoded PDF invoice — required when the target country is CN

  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.

​
China & Hong Kong destinations

USD can be delivered to bank accounts in China (CN) and Hong Kong (HK). These are destination-only corridors — CN and HK can be the target of a cross-ramp, never the source.
  • Delivered currency is USD. CNY is not yet supported. Because the source and target currencies must differ, the source currency must be MXN, DOP, or EUR (not USD).
  • Set targetCountry. Pass targetCountry: "CN" (or "HK") so USD is routed to China/Hong Kong — USD otherwise defaults to the US. If you pass an inline targetBankAccount with country: "CN", the target country is resolved from it automatically. The same targetCountry/targetRail also apply when requesting a quote.
  • Payment rail. targetRail selects how funds are delivered: LOCAL (default) for a domestic transfer, or SWIFT for an international wire.
  • Invoice required for China. invoiceFile — a Base64-encoded PDF invoice — is required whenever the target bank account country is CN.
  • Reference/memo. The optional reference field (max 140 characters) is forwarded to the payment provider and is supported across all currencies.
  • Provider-managed accounts. CN/HK payout accounts are provisioned through Capa’s payment provider; provide the fields listed in the target bank account requirements above.
Amount limits for USD delivered to CN/HK are a minimum of 10 USD and a maximum of 10,000 USD per transaction.

​
Transaction Limits

The same minimum amounts apply as for on-ramp and off-ramp transactions:
USD delivered to China (CN) or Hong Kong (HK) is limited to a minimum of 10 USD and a maximum of 10,000 USD per transaction.

​
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

​
Notifications

Capa sends webhook notifications for each status change. The following events are emitted during a cross-ramp transaction lifecycle: See the Transaction Events guide for full payload examples. Ensure your Webhook Settings are configured to receive these notifications.

​
What’s Next