> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capa.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 💎 On-Ramp

> The On-Ramp feature provided by Capa allows users to purchase cryptocurrencies using fiat currencies. Capa supports on-ramp operations for MXN (Mexican Peso) and DOP (Dominican Peso).

***

## Integration Flow

<Steps>
  <Step title="Create a user and complete KYC">
    [Create User](/reference/userpartnercontrollerv2_createuser), then [KYC verification](/reference/userpartnercontrollerv2_createverificationlink)
  </Step>

  <Step title="Get an on-ramp quote (optional)">
    [Create Quote](/reference/quotepartnerv2controller_createpartnerquote) to lock the exchange rate
  </Step>

  <Step title="Create on-ramp transaction">
    [Create On Ramp](/reference/onramppartnerv2controller_createpartneronramp)
  </Step>

  <Step title="User deposits fiat currency">
    The user deposits fiat to the bank account returned in `bankAccount`
  </Step>
</Steps>

## 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
      2. ETH - USDC
      3. SOL - USDC
      4. BSC - USDT (available only for transactions over 50,000 MXN)

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)
      {/* 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](/reference/quotepartnerv2controller_getpartnerquoterate) endpoint.
   2. To lock a guaranteed exchange rate, use the [Create Quote](/reference/quotepartnerv2controller_createpartnerquote) 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](/reference/onramppartnerv2controller_createpartneronramp)

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

| Currency | Minimum | Maximum    |
| -------- | ------- | ---------- |
| MXN      | 50 MXN  | No maximum |
| DOP      | 150 DOP | No maximum |

{/* | EUR | 20 EUR | No maximum | */}

## Funding an On-Ramp

<Warning>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.</Warning>

### 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](/reference/quotepartnerv2controller_createpartnerquote) endpoint with `cryptoAmount` and `transactionType: "ON_RAMP"`. Then immediately create the on-ramp with the returned `quoteId`.

## Transaction Status Progression

### Regular On-Ramp

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> FIAT_RECEIVED : Fiat deposited
    PENDING --> CANCELLED : Cancelled
    FIAT_RECEIVED --> IN_PROGRESS : Processing
    FIAT_RECEIVED --> CANCELLED : Cancelled
    IN_PROGRESS --> COMPLETED : Crypto sent
```

### OTC On-Ramp (large amounts)

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_PAYMENT
    PENDING_PAYMENT --> FIAT_PAYMENT_RECEIVED : Fiat deposited
    PENDING_PAYMENT --> CANCELLED : Cancelled
    FIAT_PAYMENT_RECEIVED --> GETTING_FUNDS : Processing
    GETTING_FUNDS --> WAITING_FOR_FUNDS : Waiting
    WAITING_FOR_FUNDS --> IN_PROGRESS : Processing
    IN_PROGRESS --> COMPLETED : Crypto sent
```

## Available Platforms

* **Partner API**: On-ramp operations are 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](/docs/partner-api-key-generation).
* **[Sandbox](https://sandbox.capa.fi)**: Test and manage on-ramp transactions, users, quoting, and webhook configuration in the sandbox environment.
* **[Dashboard](https://dashboard.capa.fi)**: Manage on-ramp transactions, users, quoting, and webhook configuration in production.

## 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](/docs/how-our-webhooks-work)
* Ensure that your webhook settings are correctly configured to receive timely notifications and stay informed about the status of transactions. [Webhook Settings](/reference/partnerwebhooksettingsv2controller_update)

***

## What's Next

* [/api/partner/v2/on-ramp](/reference/onramppartnerv2controller_createpartneronramp)