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

# Crear una orden de pago global

> Crea una orden de pago global de fiat a fiat. Los fondos se cobran en la moneda fiat de un país y se pagan en la de otro mediante rieles de stablecoins.

La ruta de pago global de fiat a fiat te permite mover dinero entre países sin tocar cripto en la capa de aplicación: VelaFi gestiona internamente los tramos de on-ramp y off-ramp sobre rieles de stablecoins. Configuras tanto el tramo de on-ramp (donde se cobran los fondos) como el tramo de off-ramp (donde se entregan los fondos) en una sola llamada a la API. Fija el monto del lado del on-ramp (`onRampFiatAmount`) o del lado del off-ramp (`offRampFiatAmount`); si envías ambos, `onRampFiatAmount` tiene prioridad. Un `quoteId` de la API de cotización fiat/fiat fija el tipo de cambio entre monedas.

## Endpoint

```text theme={null}
POST https://api.velafi.com/v2/order/fiat_to_fiat
```

> [!NOTE]
>
> Usa `https://api-test.velafi.com/v2/order/fiat_to_fiat` para pruebas en sandbox.

## Headers de la solicitud

| Header | Valor |
| - | - |
| `X-BH-TOKEN` | Tu token de `GET /v2/token/generate` |
| `Content-Type` | `application/json` |

## Parámetros del cuerpo de la solicitud

### Tramo de on-ramp

**onRampCountry** `string` *required*

Nombre completo del país donde se cobra el fiat (por ejemplo, `"Mexico"`).

**onRampFiat** `string` *required*

Código de moneda fiat ISO 4217 en el que paga el remitente (por ejemplo, `"MXN"`).

**onRampPaymentId** `integer` *required*

ID numérico del método de pago para cobrar el fiat del on-ramp. Consulta los IDs de métodos de pago para ver los valores admitidos.

**onRampMerchantId** `integer` *required*

ID del comercio para el tramo de on-ramp. Las solicitudes sin un comercio de on-ramp válido se rechazan.

**onRampFiatAmount** `decimal`

Monto de fiat que paga el remitente (por ejemplo, `1000.00`). Proporciona `onRampFiatAmount` u `offRampFiatAmount`; si envías ambos, `onRampFiatAmount` tiene prioridad.

**depositAlias** `string`

Alias de la cuenta virtual que se usa para el depósito fiat del on-ramp.

### Tramo de off-ramp

**offRampCountry** `string` *required*

Nombre completo del país donde se entrega el fiat (por ejemplo, `"Argentina"`).

**offRampFiat** `string` *required*

Código de moneda fiat ISO 4217 que recibe el beneficiario (por ejemplo, `"ARS"`).

**offRampPaymentId** `integer` *required*

ID numérico del método de pago de usuario del beneficiario que recibe el fiat del off-ramp. Debe ser un `userPaymentId` válido devuelto por `GET /v2/payments`.

**offRampMerchantId** `integer` *required*

ID del comercio para el tramo de off-ramp. Las solicitudes sin un comercio de off-ramp válido se rechazan.

**offRampFiatAmount** `decimal`

Monto de fiat que recibe el beneficiario (por ejemplo, `55000.00`). Se ignora cuando también se envía `onRampFiatAmount` con un valor de al menos 0.01.

### Parámetros compartidos

**clientId** `string`

Tu propio ID de referencia de la orden. Usa como máximo 40 caracteres. Debe ser único entre todas las órdenes `fiat_to_fiat` de tu cuenta; una segunda solicitud de creación con el mismo `clientId` se rechaza. Se devuelve en las respuestas de Obtener orden y Listar órdenes. Consulta [Idempotencia y reintentos](#idempotency-and-retries).

**remark** `string`

Nota opcional de texto libre adjunta a la orden.

**quoteId** `string`

ID de cotización de la API de cotización para fijar el tipo de cambio entre monedas.

**inFieldJson** `object`

Campos adicionales específicos del pago para ciertos métodos de pago.

**campos de inFieldJson**

**inFieldJson.bank** `string`

Código de banco obligatorio cuando `onRampPaymentId` es `141` (transferencia bancaria colombiana). Consulta [Códigos de bancos colombianos](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes).

## Campos de la respuesta

**code** `integer`

Código de estado de la respuesta. `200` indica éxito.

**msg** `string`

Mensaje de respuesta legible.

**data** `object`

Objeto con el resultado de la orden.

**campos de data**

**data.orderId** `integer`

El ID numérico único de la orden creada. Úsalo para obtener el estado completo de la orden y las instrucciones de pago.

## Ejemplo

```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": "my-global-pay-2024-001",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 3,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 105,
    "depositAlias": "tom_alias",
    "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampFiat": "ARS",
    "offRampPaymentId": 134,
    "remark": "Supplier payment",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
  }'
```

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

> [!TIP]
>
> Obtén el estado detallado de las órdenes de fiat a fiat con `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat`. La respuesta incluye objetos de información de pago separados para el on-ramp y el off-ramp, y un conjunto de códigos de estado propio (por ejemplo, `41` pago entrante pendiente, `51` pago saliente pendiente, `60` completada; consulta [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md)).

## Idempotencia y reintentos

Usa `clientId` para que la creación de órdenes se pueda reintentar de forma segura.

* `clientId` es opcional. Usa como máximo 40 caracteres. Debe ser único entre todas las órdenes `fiat_to_fiat` de tu cuenta, para todos tus comercios.
* Una solicitud de creación que reutiliza un `clientId` existente se rechaza con un error de envío repetido y no se crea ninguna orden nueva.
* Un `clientId` queda vinculado a su orden de forma permanente, incluso después de que la orden se cancela. Usa un `clientId` nuevo para cada orden nueva.
* `GET /v2/order/detail` busca las órdenes `fiat_to_fiat` solo por `orderId`. Para encontrar una orden por `clientId`, lista las órdenes recientes con `GET /v2/orders?orderType=fiat_to_fiat` y busca la coincidencia en el campo `clientId`.

Si una solicitud de creación agota el tiempo de espera o no devuelve respuesta, primero busca su `clientId` en la lista de órdenes. Si la orden está ahí, no la vuelvas a crear. Si no está, reintenta con el mismo `clientId`: si la primera solicitud sí creó la orden mientras tanto, el reintento se rechaza como duplicado en lugar de crear una segunda orden.

> [!NOTE]
>
> Un `quoteId` puede quedar consumido por una solicitud de creación que luego se rechaza. Solicita una nueva cotización antes de reintentar.


## Related topics

- [Crear una orden de on-ramp](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md)
- [Pagos globales (fiat a fiat)](https://docs.velafi.com/es/docs/guides/global-payments.md)
- [Crear una orden de off-ramp](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md)
- [Evento de pago global](https://docs.velafi.com/es/api-reference/webhooks/fiat-fiat-order-message-push.md)
- [Crear una cuenta](https://docs.velafi.com/es/docs/guides/creating-account.md)


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