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

# Evento de pago global

> Referencia del payload del evento GLOBAL_PAYMENT_WEBHOOK que VelaFi envía cuando cambia el estado de una orden de pago transfronterizo de fiat a fiat.

Cuando una orden de pago global de fiat a fiat creada mediante la API entra en alguno de los estados siguientes, VelaFi envía una solicitud HTTP POST firmada a tu endpoint de `GLOBAL_PAYMENT_WEBHOOK`. El payload describe ambos lados del pago transfronterizo, el on-ramp (país y moneda de origen) y el off-ramp (país y moneda de destino), junto con el estado actual de la orden. Verifica el header `signature` y responde con `{"callbackStatus": "SUCCESS"}` para confirmar la recepción.

## Headers de la solicitud

| Header | Descripción |
| - | - |
| `signature` | Firma RSA-SHA256 del cuerpo sin procesar de la solicitud, codificada en hexadecimal. Usa la `publicKey` de tu webhook para verificarla. Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md). |
| `Content-Type` | `application/json` |

## Códigos de estado de la orden

| Código | Significado |
| - | - |
| `10` | Reviewing: la orden está en revisión de cumplimiento |
| `31` | Documents Pending: se deben proporcionar los documentos requeridos |
| `41` | Payin Pending: en espera del depósito fiat del remitente |
| `51` | Payout Pending: cripto recibida, pago fiat en proceso |
| `60` | Released: orden completada |
| `71` | Payin Canceled: el tramo de on-ramp se canceló |
| `72` | Payout Canceled: el tramo de off-ramp se canceló |

Los demás estados de pagos globales no se envían.

## Campos del payload

**webhookId** `string`

ID del endpoint de webhook que entregó este evento.

**eventType** `string`

Siempre `GLOBAL_PAYMENT_WEBHOOK` para este tipo de evento.

**orderId** `string`

Identificador único de la orden de pago global.

**clientId** `string`

Identificador de orden que proporcionaste como cliente. Se omite si no proporcionaste uno.

**userId** `string`

ID de tu cuenta (usuario) de VelaFi.

**onRampCountry** `string`

Nombre del país de origen (por ejemplo, `Mexico`).

**onRampMerchantId** `string`

ID del comercio de on-ramp que procesa el pago del lado de origen. Se omite cuando no está definido.

**onRampFiat** `string`

Moneda fiat cobrada al remitente (por ejemplo, `MXN`).

**onRampFiatAmount** `string`

Monto cobrado al remitente en la moneda de origen.

**onRampFiatFee** `string`

Comisión cobrada del lado de on-ramp. Se omite cuando no está definida.

**offRampCountry** `string`

Nombre del país de destino (por ejemplo, `Hong Kong`).

**offRampMerchantId** `string`

ID del comercio de off-ramp que procesa el pago del lado de destino. Se omite cuando no está definido.

**offRampFiat** `string`

Moneda fiat entregada al destinatario (por ejemplo, `USD`).

**offRampFiatAmount** `string`

Monto entregado al destinatario en la moneda de destino.

**offRampFiatFee** `string`

Comisión cobrada del lado de off-ramp. Se omite cuando no está definida.

**orderPrice** `string`

Tipo de cambio efectivo entre las monedas de on-ramp y off-ramp.

**orderStatus** `string`

Código de estado actual de la orden. Consulta la tabla de estados de arriba.

**createTime** `string`

Marca de tiempo Unix (milisegundos) en que se creó la orden.

**updateTime** `string`

Marca de tiempo Unix (milisegundos) de la última actualización de la orden.

**timestamp** `string`

Marca de tiempo Unix (milisegundos) en que se firmó este intento de entrega.

## Ejemplo de payload

```json Cuerpo del POST entrante theme={null}
{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "GLOBAL_PAYMENT_WEBHOOK",
  "orderId": "473130522693193728",
  "clientId": "W658784738723",
  "userId": "455472",
  "onRampCountry": "Mexico",
  "onRampMerchantId": "3",
  "onRampFiat": "MXN",
  "onRampFiatAmount": "100",
  "onRampFiatFee": "0",
  "offRampCountry": "Hong Kong",
  "offRampMerchantId": "4",
  "offRampFiat": "USD",
  "offRampFiatAmount": "18",
  "offRampFiatFee": "2",
  "orderPrice": "20",
  "orderStatus": "41",
  "createTime": "1735279907000",
  "updateTime": "1735280582000",
  "timestamp": "1735280582345"
}
```

## Respuesta requerida

Devuelve el siguiente cuerpo JSON con el estado HTTP `200` para confirmar la recepción:

```json Tu respuesta theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

> [!NOTE]
>
> El webhook se dispara solo para los estados indicados arriba. Un estado puede omitirse si la orden ya avanzó al momento de intentar la entrega. El mismo evento puede llegar más de una vez, así que deduplica con `orderId` junto con `orderStatus`. Consulta [Entrega y reintentos](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md#delivery-and-retries).


## Related topics

- [Webhooks](https://docs.velafi.com/es/docs/guides/webhooks.md)
- [Pagos globales (fiat a fiat)](https://docs.velafi.com/es/docs/guides/global-payments.md)
- [Evento de pago con stablecoin](https://docs.velafi.com/es/api-reference/webhooks/stablecoin-payment-order-message-push.md)
- [Crear una orden de pago global](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-fiat-order.md)
- [Pares de trading](https://docs.velafi.com/es/docs/pairs.md)


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