Webhooks - Blockradar

Blockradar envía notificaciones de webhook cuando se crea una orden de pago de Depósito Fiat o cuando alcanza un estado final. Configura una URL de webhook en la wallet usada para crear la orden de pago para recibir estos eventos.

Consulta la guía de Webhooks para la configuración del endpoint, la verificación de firmas, los reintentos y la resolución de problemas de entrega.

Dos familias de webhooks

Depósito Fiat puede emitir dos familias de webhooks complementarias:

Familia de webhooks	Representa	Identificador
`onramp.payment-order.*`	El recurso de la orden de pago y sus instrucciones de pago	`data.id` es el ID de la orden de pago
`onramp.*`	La transacción de fiat a cripto resultante	`data.id` es el ID de la transacción

Usa onramp.payment-order.* para seguir la creación de la orden y el estado del pago. Usa onramp.* como la señal canónica de la transacción para la conciliación y la liquidación de activos. Cuando está presente, transactionId en el payload de la orden de pago vincula la orden con la transacción ONRAMP correspondiente. Los eventos de transacción son onramp.processing, onramp.success, onramp.failed y onramp.cancelled. Su relación data.paymentOrder identifica la orden de origen. Consulta Webhooks de transacciones de onramp para ver el payload canónico y las recomendaciones de manejo.

Eventos de órdenes de pago

`onramp.payment-order.created`

Se envía después de que Blockradar crea correctamente la orden de pago con el proveedor seleccionado. El payload contiene las instrucciones de pago que tu cliente usa para completar la transferencia fiat.

`onramp.payment-order.paid`

Se envía cuando Blockradar confirma que se recibió el pago fiat y que la orden de pago se liquidó correctamente. Cuando está disponible, transactionId identifica la transacción de Blockradar relacionada.

`onramp.payment-order.failed`

Se envía cuando la orden de pago no se puede completar. Obtén la orden de pago usando su id si necesitas la respuesta más reciente del proveedor y los detalles del fallo.

`onramp.payment-order.cancelled`

Se envía cuando la orden de pago se cancela antes de liquidarse correctamente. Puede desencadenarse por una solicitud de cancelación exitosa o por una actualización de estado del proveedor.

Payload

Todas las solicitudes de webhook de órdenes de pago usan el siguiente sobre:

{
  "event": "onramp.payment-order.paid",
  "data": {
    "id": "0198f028-7bb2-7000-8000-000000000001",
    "type": "onramp",
    "rail": "one_time_virtual_account",
    "reference": "deposit-order-001",
    "providerReference": "provider-order-001",
    "transactionId": "0198f02a-9201-7000-8000-000000000002",
    "status": "paid",
    "currency": "NGN",
    "amount": "100",
    "amountFiat": "150000",
    "feeFiat": "0",
    "amountFiatPayable": "150000",
    "amountFiatReceived": "150000",
    "amountSettled": "100",
    "expiresAt": "2026-08-01T13:00:00.000Z",
    "paymentInstructions": {
      "type": "one_time_virtual_account",
      "bank": {
        "name": "Example Bank",
        "code": null,
        "accountName": "Blockradar Payment",
        "accountNumber": "1234567890"
      },
      "expiresAt": "2026-08-01T13:00:00.000Z",
      "metadata": {
        "providerReference": "provider-order-001",
        "providerStatus": "settled",
        "currency": "NGN",
        "amountToTransfer": "150000",
        "targetAmount": "100"
      }
    },
    "metadata": {
      "orderId": "merchant-order-001"
    },
    "provider": {
      "id": "0198f020-0000-7000-8000-000000000003",
      "slug": "paycrest",
      "name": "Paycrest"
    },
    "wallet": {
      "id": "0198f020-0000-7000-8000-000000000004",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "address": null,
    "asset": {
      "id": "0198f020-0000-7000-8000-000000000005",
      "symbol": "USDC",
      "name": "USD Coin"
    },
    "customer": null,
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:10:00.000Z"
  }
}

Se usa la misma estructura de data para todos los eventos. Los campos que no están disponibles en la etapa actual pueden ser null. En particular, transactionId, amountFiatReceived y amountSettled podrían no estar presentes en el evento onramp.payment-order.created.

Evento	`data.status` esperado	Significado
`onramp.payment-order.created`	`pending` o `processing`	La orden de pago se creó y está a la espera del pago.
`onramp.payment-order.paid`	`paid`	El pago y la liquidación se completaron correctamente.
`onramp.payment-order.failed`	`failed`	La orden de pago no se pudo completar.
`onramp.payment-order.cancelled`	`cancelled`	La orden de pago se canceló.

Manejo de eventos

Devuelve una respuesta 2xx exitosa en cuanto aceptes el evento.
Usa data.id como identificador de la orden de pago y haz que el procesamiento sea idempotente.
No asumas que los eventos llegan una sola vez ni en un orden concreto.
Usa event y data.status juntos al actualizar la orden en tu sistema.
Trata onramp.payment-order.paid como el evento final de éxito.
Trata onramp.success como el evento final de éxito de la transacción de onramp correspondiente.

​Dos familias de webhooks

​Eventos de órdenes de pago

​onramp.payment-order.created

​onramp.payment-order.paid

​onramp.payment-order.failed

​onramp.payment-order.cancelled

​Payload

​Manejo de eventos

Dos familias de webhooks

Eventos de órdenes de pago

`onramp.payment-order.created`

`onramp.payment-order.paid`

`onramp.payment-order.failed`

`onramp.payment-order.cancelled`

Payload

Manejo de eventos