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

# 🔄 Cross-Ramp

> The Cross-Ramp feature provided by Capa allows users to convert between different fiat currencies (e.g., MXN to USD). Capa supports cross-ramp operations between MXN, DOP, USD, and EUR.

***

## 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](#china--hong-kong-destinations) for the additional requirements.

## 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 a cross-ramp quote (optional)">
    [Create Cross-Ramp Quote](/reference/crossramppartnerv2controller_createpartnercrossrampquote) to lock the exchange rate
  </Step>

  <Step title="Create cross-ramp transaction">
    [Create Cross-Ramp](/reference/crossramppartnerv2controller_createpartnercrossramp)
  </Step>

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

## 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](/reference/crossramppartnerv2controller_getpartnercrossrampquoterate) endpoint with `sourceCurrency`, `targetCurrency`, and either `sourceAmount` or `targetAmount`.
   2. To lock a guaranteed exchange rate, use the [Create Cross-Ramp Quote](/reference/crossramppartnerv2controller_createpartnercrossrampquote) 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:

   | Country     | Required Fields                                                                                                                                                                                      |
   | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **MX**      | `accountIdentifier` (18-digit CLABE)                                                                                                                                                                 |
   | **DO**      | `accountIdentifier`, `bankName`, `accountType`, `documentIdentifier`, `documentType`                                                                                                                 |
   | **US**      | `accountIdentifier`, `bankName`, `routingNumber` (9-digit ABA), `accountHolder` (`type`, `firstName`/`lastName` or `businessName`), `address` (`streetLine1`, `city`, `postalCode`, `country`)       |
   | **SEPA**    | `iban`, `bic`, `bankName`, `accountHolder` (`type`, `firstName`/`lastName` or `businessName`)                                                                                                        |
   | **CN / HK** | `accountIdentifier`, `bankName`, `accountType`, `accountHolder`, `address`; `bic` optional (used for SWIFT). Destination only — see [China & Hong Kong destinations](#china--hong-kong-destinations) |

   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](/reference/crossramppartnerv2controller_createpartnercrossramp) 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](/docs/receivers))
   * `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](/reference/crossramppartnerv2controller_createpartnercrossrampquote).
* **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](#target-bank-account) above.

<Note>Amount limits for USD delivered to CN/HK are a minimum of **10 USD** and a maximum of **10,000 USD** per transaction.</Note>

## Transaction Limits

The same minimum amounts apply as for on-ramp and off-ramp transactions:

| Currency | Minimum | Maximum    |
| -------- | ------- | ---------- |
| MXN      | 50 MXN  | No maximum |
| DOP      | 150 DOP | No maximum |
| USD      | 20 USD  | No maximum |
| EUR      | 20 EUR  | No maximum |

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

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

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

### 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`.

<Note>When using `quoteId`, do not pass `sourceAmount`, `targetAmount`, `sourceCurrency`, or `targetCurrency` — these values are taken from the quote.</Note>

## Transaction Status Progression

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_FUNDS
    PENDING_FUNDS --> FUNDS_RECEIVED : Source fiat deposited
    PENDING_FUNDS --> CANCELLED : Cancelled
    FUNDS_RECEIVED --> IN_PROGRESS : Processing conversion
    IN_PROGRESS --> AWAITING_FUND_TRANSFER : Conversion complete
    AWAITING_FUND_TRANSFER --> COMPLETED : Target fiat delivered
```

| Status                   | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `PENDING_FUNDS`          | Transaction created, waiting for the user to deposit source fiat |
| `FUNDS_RECEIVED`         | Source fiat has been received                                    |
| `IN_PROGRESS`            | Conversion is being processed                                    |
| `AWAITING_FUND_TRANSFER` | Conversion complete, awaiting delivery to target bank account    |
| `COMPLETED`              | Target fiat has been delivered to the bank account               |
| `CANCELLED`              | Transaction 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:

| Event                               | Triggered When                   |
| ----------------------------------- | -------------------------------- |
| `CREATED_CROSS_RAMP`                | Transaction created              |
| `FUNDS_RECEIVED_CROSS_RAMP`         | Source fiat received             |
| `STARTED_PROCESSING_CROSS_RAMP`     | Conversion processing begins     |
| `AWAITING_FUND_TRANSFER_CROSS_RAMP` | Awaiting delivery to target bank |
| `COMPLETED_CROSS_RAMP`              | Target fiat delivered            |
| `CANCELLED_CROSS_RAMP`              | Transaction cancelled            |

See the [Transaction Events](/docs/transaction-events#cross-ramp-events) guide for full payload examples. Ensure your [Webhook Settings](/reference/partnerwebhooksettingsv2controller_update) are configured to receive these notifications.

***

## What's Next

* [Create Cross-Ramp](/reference/crossramppartnerv2controller_createpartnercrossramp)
* [Cross-Ramp Quote Rate](/reference/crossramppartnerv2controller_getpartnercrossrampquoterate)
* [Transaction Events](/docs/transaction-events)