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

# Global Payments (Fiat to Fiat)

> Send fiat currency across borders and deliver local fiat to any bank account using VelaFi's stablecoin-powered global payment rails.

VelaFi's fiat-to-fiat global payments let you move money between countries without requiring either the sender or recipient to hold cryptocurrency. Under the hood, VelaFi bridges the two local currencies through stablecoin rails — converting the sender's fiat to a stablecoin, routing it cross-border, then converting it back into the recipient's local fiat and depositing it directly into their bank account. The entire flow is abstracted into a single API call, giving you cross-border payment capability without building or maintaining any forex or crypto infrastructure.

## How it works

### Confirm prerequisites

Two merchant accounts are involved in every global payment — one on each side of the transfer:

* **Sender merchant (on-ramp side)** — must have an activated on-ramp fiat account for the sending country and currency.
* **Recipient merchant (off-ramp side)** — must have an activated off-ramp fiat account for the receiving country and currency.
* **Beneficiary registered** — the recipient's bank account must be added as a beneficiary on the off-ramp merchant. The resulting `offRampPaymentId` (a `userPaymentId`) is required when creating the order.
* **API key available** — all requests require the `X-BH-TOKEN` header.

### Get a quote (optional)

Request a real-time cross-currency exchange rate before creating the order. The rate reflects the full on-ramp → stablecoin → off-ramp conversion chain.

**Endpoint:** `GET /v2/user/fiat-quote`

Pass the sending country, sending fiat currency, receiving country, and receiving fiat currency as query parameters. The response returns the current `price` (units of receiving fiat per unit of sending fiat) and, with `createQuoteId=true`, a single-use `quoteId` that locks the rate for 20 seconds in production (300 seconds in the sandbox).

> [!TIP]
>
> Pass the returned `quoteId` in the order creation request to guarantee the quoted rate. If you omit it, the order executes at the live market rate at placement time.

### Create the global payment order

Submit a `POST` request to `/v2/order/fiat_to_fiat`. VelaFi receives the on-ramp fiat, converts through stablecoin rails, and initiates the off-ramp payout to the beneficiary.

**Endpoint:** `POST /v2/order/fiat_to_fiat`

#### Request parameters

**onRampCountry** `string` *required*

Name of the sending country (e.g., `"Mexico"`).

**onRampFiat** `string` *required*

Fiat currency the sender pays in (e.g., `"MXN"`).

**onRampPaymentId** `number` *required*

Payment method ID for the on-ramp deposit (e.g., SPEI for Mexico). See [Payment Method IDs](https://docs.velafi.com/docs/payment-methods.md).

**offRampCountry** `string` *required*

Name of the receiving country (e.g., `"Argentina"`).

**offRampFiat** `string` *required*

Fiat currency the recipient receives (e.g., `"ARS"`).

**offRampPaymentId** `number` *required*

Beneficiary payment ID for the off-ramp payout — the `userPaymentId` from the registered beneficiary record. See [Get Beneficiaries](https://docs.velafi.com/api-reference/beneficiary/get-beneficiary.md).

**onRampFiatAmount** `decimal`

Amount of fiat the sender pays (e.g., `1000.00`). Provide either `onRampFiatAmount` or `offRampFiatAmount`; if both are sent, `onRampFiatAmount` is used.

**offRampFiatAmount** `decimal`

Target amount the recipient should receive (e.g., `55966.40`). Used only when `onRampFiatAmount` is not sent.

**quoteId** `string`

Quote ID from `GET /v2/user/fiat-quote`. Pass this to lock the quoted exchange rate.

**clientId** `string`

Your own order reference ID. Use at most 40 characters; it must be unique across all your `fiat_to_fiat` orders, and a repeated `clientId` is rejected. Returned in subsequent order queries. See [Idempotency and retries](https://docs.velafi.com/api-reference/order/create-a-fiat-to-fiat-order.md#idempotency-and-retries).

**onRampMerchantId** `number` *required*

ID of the on-ramp (sender) merchant. Requests without a valid on-ramp merchant are rejected.

**offRampMerchantId** `number` *required*

ID of the off-ramp (recipient) merchant. Requests without a valid off-ramp merchant are rejected.

**depositAlias** `string`

Alias of a virtual account to associate with the on-ramp deposit, if your setup uses virtual account routing.

**inFieldJson** `object`

Additional structured fields required by certain payment methods.

**inFieldJson fields**

**inFieldJson.bank** `enum`

Bank code required when using Colombian on-ramp payment methods (e.g., `onRampPaymentId=141`). See the [Colombian bank codes list](https://docs.velafi.com/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes-1).

**remark** `string`

Free-text note attached to the order for your reference.

#### Example request

```bash theme={null}
curl -X POST https://api.velafi.com/v2/order/fiat_to_fiat \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "gp-order-001",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 3,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 105,
          "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampFiat": "ARS",
    "offRampPaymentId": 134,
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "remark": "Cross-border payment for invoice #9901"
  }'
```

#### Example response

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": 1123123123
  }
}
```

### Monitor order status

Poll `GET /v2/order/detail` with `orderType=fiat_to_fiat`, or configure a [webhook](https://docs.velafi.com/docs/guides/webhooks.md) with the `GLOBAL_PAYMENT_WEBHOOK` event type to receive real-time status updates.

**Endpoint:** `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat`

#### Example request

```bash theme={null}
curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
  -H "X-BH-TOKEN: YOUR_TOKEN"
```

#### Example response

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "494541042692263936",
    "clientId": "gp-order-001",
    "onRampMerchantId": 3,
    "onRampPaymentId": 105,
          "onRampCountry": "Mexico",
    "onRampFiat": "MXN",
    "onRampFiatAmount": "1000",
    "onRampFiatFee": "1",
    "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampPaymentId": 134,
    "offRampFiat": "ARS",
    "offRampFiatAmount": "55966.40",
    "offArriveRampFiatAmount": "55965.40",
    "offRampFiatFee": "1",
    "orderPrice": "55.9664",
    "orderStatus": 60,
    "onRampPaymentInfo": {
      "Cuenta CLABE": "000000000000000001"
    },
    "offRampPaymentInfo": {
      "Cuenta CLABE": "000000000000000003"
    },
    "createTime": "1740384573000",
    "completedTime": "1740384573000"
  }
}
```

#### Response fields

**orderId** `string`

Unique identifier for this order.

**clientId** `string`

Your own reference ID, echoed back from the create request.

**onRampMerchantId** `number`

ID of the on-ramp (sender) merchant.

**onRampPaymentId** `number`

Payment method ID used for the on-ramp deposit.

**onRampCountry** `string`

Country where the fiat payment originates.

**onRampFiat** `string`

Fiat currency paid by the sender.

**onRampFiatAmount** `string`

Amount of fiat the sender paid.

**onRampFiatFee** `string`

Fee charged on the on-ramp side.

**offRampCountry** `string`

Country where the fiat payout is delivered.

**offRampMerchantId** `number`

ID of the off-ramp (recipient) merchant.

**offRampPaymentId** `number`

Beneficiary payment ID used for the off-ramp payout.

**offRampFiat** `string`

Fiat currency received by the beneficiary.

**offRampFiatAmount** `string`

Gross fiat amount sent to the recipient before fees.

**offArriveRampFiatAmount** `string`

Net fiat amount that actually arrives in the recipient's account after fees.

**offRampFiatFee** `string`

Fee charged on the off-ramp side.

**orderPrice** `string`

Exchange rate (units of off-ramp fiat per unit of on-ramp fiat) at order creation.

**orderStatus** `number`

Current status code. See [Order Statuses](https://docs.velafi.com/docs/order-statuses.md).

**onRampPaymentInfo** `object`

On-ramp payment instructions (e.g., bank account the sender deposits into).

**offRampPaymentInfo** `object`

Off-ramp payment details (e.g., bank account the recipient receives funds into).

**createTime** `string`

Order creation timestamp in milliseconds (Unix epoch).

**completedTime** `string`

Order completion timestamp in milliseconds (Unix epoch).

#### Order status codes

Global payment orders use their own status codes: `10`, `11`, `12`, `31`, `41`, `51`, `60`, `71`, `72` and `90`. See [Order Statuses](https://docs.velafi.com/docs/order-statuses.md) for what each code means and which codes end an order.

## Supported global payment pairs

VelaFi supports cross-border fiat payments between the following country pairs. Retrieve the complete up-to-date list via the [Fiat/Fiat Pairs API endpoint](https://docs.velafi.com/api-reference/basic-configuration/get-fiat-fiat-pairs.md).

| Sending country | Sending currency | Receiving country | Receiving currency |
| - | - | - | - |
| 🇦🇷 Argentina | ARS | 🇲🇽 Mexico | MXN |
| 🇦🇷 Argentina | ARS | 🇺🇸 United States | USD |
| 🇧🇷 Brazil | BRL | 🇦🇷 Argentina | ARS |
| 🇧🇷 Brazil | BRL | 🇭🇰 Hong Kong | USD |
| 🇧🇷 Brazil | BRL | 🌐 Global | USD |
| 🇨🇴 Colombia | COP | 🇲🇽 Mexico | MXN |
| 🇲🇽 Mexico | MXN | 🇦🇷 Argentina | ARS |
| 🇲🇽 Mexico | MXN | 🇨🇴 Colombia | COP |
| 🇲🇽 Mexico | MXN | 🇭🇰 Hong Kong | USD |
| 🇲🇽 Mexico | MXN | 🇺🇸 United States | USD |
| 🇲🇽 Mexico | MXN | 🌐 Global | USD |
| 🇺🇸 United States | USD | 🇦🇷 Argentina | ARS |
| 🇺🇸 United States | USD | 🇲🇽 Mexico | MXN |

> [!NOTE]
>
> The "Global" receiving region covers USD payouts that are not tied to a specific country — useful for routing funds to international USD accounts. Contact VelaFi support if you need a pair that is not listed here.


## Related topics

- [List Fiat→Fiat Payment Methods](https://docs.velafi.com/api-reference/basic-configuration/get-fiat-fiat-payment-methods.md)
- [Webhooks](https://docs.velafi.com/docs/guides/webhooks.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)
- [Order Statuses](https://docs.velafi.com/docs/order-statuses.md)
- [List Fiat→Crypto Payment Methods](https://docs.velafi.com/api-reference/basic-configuration/get-fiat-crypto-payment-methods.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.