> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recibe actualizaciones de estado de las órdenes de pago de Depósito Fiat.

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.

<Info>
  Consulta la [guía de Webhooks](/es/utilities/webhooks) para la configuración
  del endpoint, la verificación de firmas, los reintentos y la resolución de
  problemas de entrega.
</Info>

## 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](/es/utilities/webhooks#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:

```json theme={null}
{
  "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.


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