Evento de pago global

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

string

ID del endpoint de webhook que entregó este evento.

string

Siempre GLOBAL_PAYMENT_WEBHOOK para este tipo de evento.

string

Identificador único de la orden de pago global.

string

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

string

ID de tu cuenta (usuario) de VelaFi.

string

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

string

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

string

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

string

Monto cobrado al remitente en la moneda de origen.

string

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

string

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

string

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

string

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

string

Monto entregado al destinatario en la moneda de destino.

string

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

string

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

string

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

string

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

string

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

string

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

Ejemplo de payload

Cuerpo del POST entrante

{
  "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:

Tu respuesta

{
  "callbackStatus": "SUCCESS"
}

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.

⌘I

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Evento de pago global

Headers de la solicitud

Códigos de estado de la orden

Campos del payload

Ejemplo de payload

Respuesta requerida

​Headers de la solicitud

​Códigos de estado de la orden

​Campos del payload

​Ejemplo de payload

​Respuesta requerida

Headers de la solicitud

Códigos de estado de la orden

Campos del payload

Ejemplo de payload

Respuesta requerida