Skip to main content

​
Integration Flow

1

Create a user and complete KYC

Create User, then KYC verification
2

Get an on-ramp quote (optional)

Create Quote to lock the exchange rate
3

Create on-ramp transaction

Create On Ramp
4

User deposits fiat currency

The user deposits fiat to the bank account returned in bankAccount

​
How to do an On-Ramp Operation

To successfully execute an on-ramp operation, follow these steps:

  1. ​
    Select the Blockchain and Token:

    1. The following is a list of the Blockchains and Tokens
    2. The list of Blockchains - Tokens symbols supported in Capa are:
      1. POL - USDC, USDT, POL, MATIC
      2. BSC - BNB
      3. BASE - USDC, USDC.e, USDbC, ETH, MXNe, cbBTC, wUSDL
      4. OP - USDC, ETH
      5. ARB - USDC, ETH
      6. SOL - USDC, SOL, USDY, PYSUD
      7. WLD - WLD
      8. STK - USDC, STK
      9. ETH - USDC, ETH, wBTC
        For faster completion time use USDC in Polygon POS

  2. ​
    Select the Fiat Currency:

    1. Choose the supported fiat currency for the transaction. Capa currently supports the following fiat currencies:
      1. MXN (Mexican Peso)
      2. DOP (Dominican Peso)
      3. USD (US Dollar)
      4. EUR (Euro)

  3. ​
    Quoting:

    1. To show a real-time estimate of how much crypto the user will get with the selected Blockchain Token, Fiat Currency and Amount use the Get Quote Rate endpoint.
    2. To lock a guaranteed exchange rate, use the Create 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 fiatAmount or cryptoAmount in the quote request.
    4. Forward Settlement (MXN OTC only): For MXN orders above 50,000 MXN (OTC), the locked quote supports a forwardingDays parameter (0-4) that lets you lock the rate now but settle the transaction T+N days later.

  4. ​
    Obtain User Wallet Address:

    1. Ensure to ask the user for their wallet address where the crypto wants to be deposited. Make sure to verify that this is a valid address for the selected blockchain, and save it for step 6.

  5. ​
    Show Bank Information:

    1. After KYC verification, users in Mexico automatically get a dedicated CLABE (bank account identifier) created for them. For the Dominican Republic, a single Capa bank account is used. For both countries you can get the bank information after creating the transaction — it is also returned in the on-ramp creation response under bankAccount.
    CLABE Behavior (Mexico):
    • The CLABE is automatically created when the user’s KYC is verified — no separate API call is needed.
    • The CLABE is permanent and reusable across all on-ramp transactions for that user. It does not expire.
    • The CLABE alone is sufficient for SPEI deposits — the account holder name auto-populates in the sender’s banking app.

  6. ​
    Execute the On-Ramp:

With all required information gathered, you can proceed to execute the on-ramp operation using the Capa API. See the documentation to execute the on ramp Create On Ramp Transaction Key parameters:
  • userId (required): The user’s Capa ID
  • destinationWalletAddress (required): Where the crypto will be sent
  • fiatCurrency, blockchainSymbol, tokenSymbol (required): The selected currency, blockchain, and token
  • fiatAmount or cryptoAmount: The amount to convert
  • quoteId (optional): A locked quote ID from the Create Quote endpoint
  • premiumSpread (optional): A spread percentage to apply to the exchange rate

​
Transaction Limits

CurrencyMinimumMaximum
MXN50 MXNNo maximum
DOP150 DOPNo maximum
USD20 USDNo maximum
EUR20 EURNo maximum

​
Funding an On-Ramp

An on-ramp transaction must be created before making the fiat deposit. Deposits received without a matching active on-ramp order will be refunded at end of business day.

​
Funding a Specific Order

For MXN (SPEI) deposits: To fund a specific on-ramp transaction, include the transaction ID (with or without dashes) in the SPEI concepto field. This ensures the deposit is matched to the correct order regardless of amount or creation order. If the concepto does not contain a transaction ID, the deposit is matched to the user’s open on-ramp orders by amount + CLABE. If multiple orders share the same amount, the oldest order is matched first. If neither the transaction ID nor the amount + CLABE combination matches an open order, the deposit is refunded at end of business day. For DOP, USD, and EUR deposits: Bank details and deposit instructions are returned in the on-ramp creation response under bankAccount. Deposits are matched internally by Capa — no concepto or reference field is required.

​
Multiple Concurrent Orders

You can have multiple on-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 on-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. 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. Quote locking is available for all amounts — there is no minimum. A quote is optional — if no quoteId is provided, the amount is calculated at the exchange rate at the time of funding.

​
On-Ramp by Destination Amount

To specify how much crypto the user should receive (instead of how much fiat they’ll send), use the Create Quote endpoint with cryptoAmount and transactionType: "ON_RAMP". Then immediately create the on-ramp with the returned quoteId.

​
Transaction Status Progression

​
Regular On-Ramp

​
OTC On-Ramp (large amounts)

​
Available Platforms

Capa.fi : Users can perform on-ramp operations directly on the Capa.fi website.
Partner API: For partners, on-ramp operations can be performed via the API using the Partner API key. For instructions on generating and using the API key, refer to the 🔑 API Key Generation 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.
    Email Notifications for Users (Optional): Users receive email notifications regarding their transaction status and other relevant updates. 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