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

# Pagos globales (fiat a fiat)

> Envía moneda fiat entre países y entrega fiat local en cualquier cuenta bancaria con los canales de pagos globales de VelaFi basados en stablecoins.

Los pagos globales fiat a fiat de VelaFi te permiten mover dinero entre países sin que el remitente ni el destinatario tengan que tener criptomonedas. Internamente, VelaFi conecta las dos monedas locales mediante canales de stablecoin: convierte el fiat del remitente a una stablecoin, la envía al otro país y luego la convierte de nuevo a la moneda fiat local del destinatario para depositarla directamente en su cuenta bancaria. Todo el flujo se resume en una sola llamada a la API, lo que te da capacidad de pagos transfronterizos sin construir ni mantener infraestructura de divisas ni de cripto.

## Cómo funciona

### Confirma los requisitos previos

En cada pago global participan dos cuentas de comercio, una de cada lado de la transferencia:

* **Comercio remitente (lado on-ramp)**: debe tener activada una cuenta fiat de on-ramp para el país y la moneda de envío.
* **Comercio destinatario (lado off-ramp)**: debe tener activada una cuenta fiat de off-ramp para el país y la moneda de recepción.
* **Beneficiario registrado**: la cuenta bancaria del destinatario debe estar agregada como beneficiario en el comercio de off-ramp. El `offRampPaymentId` resultante (un `userPaymentId`) es obligatorio al crear la orden.
* **Clave de API disponible**: todas las solicitudes requieren el header `X-BH-TOKEN`.

### Obtén una cotización (opcional)

Solicita un tipo de cambio entre monedas en tiempo real antes de crear la orden. El tipo de cambio refleja toda la cadena de conversión on-ramp → stablecoin → off-ramp.

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

Envía como parámetros de consulta el país de envío, la moneda fiat de envío, el país de recepción y la moneda fiat de recepción. La respuesta devuelve el `price` vigente (unidades de fiat de recepción por unidad de fiat de envío) y, con `createQuoteId=true`, un `quoteId` de un solo uso que fija el tipo de cambio durante 20 segundos en producción (300 segundos en el sandbox).

> [!TIP]
>
> Envía el `quoteId` devuelto en la solicitud de creación de la orden para garantizar el tipo de cambio cotizado. Si lo omites, la orden se ejecuta al tipo de cambio de mercado vigente al momento de crearla.

### Crea la orden de pago global

Envía una solicitud `POST` a `/v2/order/fiat_to_fiat`. VelaFi recibe el fiat de on-ramp, lo convierte mediante canales de stablecoin e inicia el pago de off-ramp al beneficiario.

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

#### Parámetros de la solicitud

**onRampCountry** `string` *required*

Nombre del país de envío (p. ej., `"Mexico"`).

**onRampFiat** `string` *required*

Moneda fiat con la que paga el remitente (p. ej., `"MXN"`).

**onRampPaymentId** `number` *required*

ID del método de pago para el depósito de on-ramp (p. ej., SPEI para México). Consulta [IDs de métodos de pago](https://docs.velafi.com/es/docs/payment-methods.md).

**offRampCountry** `string` *required*

Nombre del país de recepción (p. ej., `"Argentina"`).

**offRampFiat** `string` *required*

Moneda fiat que recibe el destinatario (p. ej., `"ARS"`).

**offRampPaymentId** `number` *required*

ID de pago del beneficiario para el pago de off-ramp: el `userPaymentId` del registro del beneficiario. Consulta [Obtener beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md).

**onRampFiatAmount** `decimal`

Monto de fiat que paga el remitente (p. ej., `1000.00`). Envía `onRampFiatAmount` u `offRampFiatAmount`; si envías ambos, se usa `onRampFiatAmount`.

**offRampFiatAmount** `decimal`

Monto objetivo que debe recibir el destinatario (p. ej., `55966.40`). Solo se usa cuando no se envía `onRampFiatAmount`.

**quoteId** `string`

ID de cotización de `GET /v2/user/fiat-quote`. Envíalo para fijar el tipo de cambio cotizado.

**clientId** `string`

Tu propio ID de referencia de la orden. Usa como máximo 40 caracteres; debe ser único entre todas tus órdenes `fiat_to_fiat`, y un `clientId` repetido se rechaza. Se devuelve en las consultas posteriores de la orden. Consulta [Idempotencia y reintentos](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-fiat-order.md#idempotency-and-retries).

**onRampMerchantId** `number` *required*

ID del comercio de on-ramp (remitente). Las solicitudes sin un comercio de on-ramp válido se rechazan.

**offRampMerchantId** `number` *required*

ID del comercio de off-ramp (destinatario). Las solicitudes sin un comercio de off-ramp válido se rechazan.

**depositAlias** `string`

Alias de una cuenta virtual que se asociará con el depósito de on-ramp, si tu configuración usa enrutamiento por cuentas virtuales.

**inFieldJson** `object`

Campos estructurados adicionales que requieren ciertos métodos de pago.

**Campos de inFieldJson**

**inFieldJson.bank** `enum`

Código de banco obligatorio al usar métodos de pago de on-ramp de Colombia (p. ej., `onRampPaymentId=141`). Consulta la [lista de códigos de bancos de Colombia](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes).

**remark** `string`

Nota de texto libre adjunta a la orden para tu referencia.

#### Ejemplo de solicitud

```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"
  }'
```

#### Ejemplo de respuesta

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

### Monitorea el estado de la orden

Consulta periódicamente `GET /v2/order/detail` con `orderType=fiat_to_fiat`, o configura un [webhook](https://docs.velafi.com/es/docs/guides/webhooks.md) con el tipo de evento `GLOBAL_PAYMENT_WEBHOOK` para recibir actualizaciones de estado en tiempo real.

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

#### Ejemplo de solicitud

```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"
```

#### Ejemplo de respuesta

```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"
  }
}
```

#### Campos de la respuesta

**orderId** `string`

Identificador único de esta orden.

**clientId** `string`

Tu propio ID de referencia, devuelto tal como lo enviaste en la solicitud de creación.

**onRampMerchantId** `number`

ID del comercio de on-ramp (remitente).

**onRampPaymentId** `number`

ID del método de pago usado para el depósito de on-ramp.

**onRampCountry** `string`

País donde se origina el pago fiat.

**onRampFiat** `string`

Moneda fiat pagada por el remitente.

**onRampFiatAmount** `string`

Monto de fiat que pagó el remitente.

**onRampFiatFee** `string`

Comisión cobrada del lado on-ramp.

**offRampCountry** `string`

País donde se entrega el pago fiat.

**offRampMerchantId** `number`

ID del comercio de off-ramp (destinatario).

**offRampPaymentId** `number`

ID de pago del beneficiario usado para el pago de off-ramp.

**offRampFiat** `string`

Moneda fiat que recibe el beneficiario.

**offRampFiatAmount** `string`

Monto bruto de fiat enviado al destinatario antes de comisiones.

**offArriveRampFiatAmount** `string`

Monto neto de fiat que realmente llega a la cuenta del destinatario después de comisiones.

**offRampFiatFee** `string`

Comisión cobrada del lado off-ramp.

**orderPrice** `string`

Tipo de cambio (unidades de fiat de off-ramp por unidad de fiat de on-ramp) al crear la orden.

**orderStatus** `number`

Código de estado actual. Consulta [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md).

**onRampPaymentInfo** `object`

Instrucciones de pago de on-ramp (p. ej., la cuenta bancaria a la que deposita el remitente).

**offRampPaymentInfo** `object`

Datos de pago de off-ramp (p. ej., la cuenta bancaria en la que el destinatario recibe los fondos).

**createTime** `string`

Marca de tiempo de creación de la orden en milisegundos (Unix epoch).

**completedTime** `string`

Marca de tiempo de finalización de la orden en milisegundos (Unix epoch).

#### Códigos de estado de la orden

Las órdenes de pago global usan sus propios códigos de estado: `10`, `11`, `12`, `31`, `41`, `51`, `60`, `71`, `72` y `90`. Consulta [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md) para ver qué significa cada código y cuáles finalizan una orden.

## Pares de pagos globales disponibles

VelaFi admite pagos fiat transfronterizos entre los siguientes pares de países. Obtén la lista completa y actualizada con el [endpoint de pares fiat/fiat](https://docs.velafi.com/es/api-reference/basic-configuration/get-fiat-fiat-pairs.md).

| País de envío | Moneda de envío | País de recepción | Moneda de recepción |
| - | - | - | - |
| 🇦🇷 Argentina | ARS | 🇲🇽 México | MXN |
| 🇦🇷 Argentina | ARS | 🇺🇸 Estados Unidos | USD |
| 🇧🇷 Brasil | BRL | 🇦🇷 Argentina | ARS |
| 🇧🇷 Brasil | BRL | 🇭🇰 Hong Kong | USD |
| 🇧🇷 Brasil | BRL | 🌐 Global | USD |
| 🇨🇴 Colombia | COP | 🇲🇽 México | MXN |
| 🇲🇽 México | MXN | 🇦🇷 Argentina | ARS |
| 🇲🇽 México | MXN | 🇨🇴 Colombia | COP |
| 🇲🇽 México | MXN | 🇭🇰 Hong Kong | USD |
| 🇲🇽 México | MXN | 🇺🇸 Estados Unidos | USD |
| 🇲🇽 México | MXN | 🌐 Global | USD |
| 🇺🇸 Estados Unidos | USD | 🇦🇷 Argentina | ARS |
| 🇺🇸 Estados Unidos | USD | 🇲🇽 México | MXN |

> [!NOTE]
>
> La región de recepción "Global" cubre pagos en USD que no están ligados a un país específico; es útil para enviar fondos a cuentas internacionales en USD. Contacta al soporte de VelaFi si necesitas un par que no aparece aquí.


## Related topics

- [Listar métodos de pago fiat→fiat](https://docs.velafi.com/es/api-reference/basic-configuration/get-fiat-fiat-payment-methods.md)
- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md)
- [Listar métodos de pago cripto→fiat](https://docs.velafi.com/es/api-reference/basic-configuration/get-crypto-fiat-payment-methods.md)
- [Listar métodos de pago fiat→cripto](https://docs.velafi.com/es/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.