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.

​
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.

​
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

​
Transaction Lifecycle

Cross-ramp transactions go through the following statuses:
  1. PENDING_FUNDS: Transaction created, waiting for the user to deposit source fiat
  2. FUNDS_RECEIVED: Source fiat has been received
  3. IN_PROGRESS: Conversion is being processed
  4. AWAITING_FUND_TRANSFER: Conversion complete, awaiting delivery to target bank
  5. COMPLETED: Target fiat has been delivered
A transaction can be CANCELLED at any stage. For webhook notifications on these status changes, see the Transaction Events guide.

​
Notifications

Capa sends notifications to keep you updated on transaction statuses:
  • Webhooks for Partners: Capa posts updates to the configured partner webhooks to notify of transaction status changes. Webhooks
  • Ensure that your webhook settings are correctly configured to receive timely notifications and stay informed about the status of transactions. Webhook Settings

​
What’s Next