Webhooks - Blockradar

A Blockradar envia notificações de webhook quando uma ordem de pagamento do Depósito em Fiat é criada ou atinge um estado final. Configure uma URL de webhook na carteira usada para criar a ordem de pagamento para receber esses eventos.

Consulte o guia de Webhooks para configuração de endpoints, verificação de assinatura, novas tentativas e solução de problemas de entrega.

Duas famílias de webhooks

O Depósito em Fiat pode emitir duas famílias de webhooks complementares:

Família de webhooks	Representa	Identificador
`onramp.payment-order.*`	O recurso de ordem de pagamento e suas instruções de pagamento	`data.id` é o ID da ordem de pagamento
`onramp.*`	A transação de fiat para cripto resultante	`data.id` é o ID da transação

Use onramp.payment-order.* para acompanhar a criação da ordem e o status do pagamento. Use onramp.* como o sinal canônico da transação para conciliação e liquidação de ativos. Quando preenchido, o transactionId no payload da ordem de pagamento vincula a ordem à transação ONRAMP correspondente. Os eventos de transação são onramp.processing, onramp.success, onramp.failed e onramp.cancelled. A relação data.paymentOrder desses eventos identifica a ordem de origem. Consulte Webhooks de transação de onramp para o payload canônico e as orientações de tratamento.

Eventos da ordem de pagamento

`onramp.payment-order.created`

Enviado depois que a Blockradar cria com sucesso a ordem de pagamento com o provedor selecionado. O payload contém as instruções de pagamento que seu cliente usa para concluir a transferência em fiat.

`onramp.payment-order.paid`

Enviado quando a Blockradar confirma que o pagamento em fiat foi recebido e a ordem de pagamento foi liquidada com sucesso. Quando disponível, o transactionId identifica a transação relacionada da Blockradar.

`onramp.payment-order.failed`

Enviado quando a ordem de pagamento não pode ser concluída. Consulte a ordem de pagamento pelo seu id se você precisar da resposta mais recente do provedor e dos detalhes da falha.

`onramp.payment-order.cancelled`

Enviado quando a ordem de pagamento é cancelada antes da liquidação bem-sucedida. Isso pode ser acionado por uma solicitação de cancelamento bem-sucedida ou por uma atualização de status do provedor.

Payload

Todas as requisições de webhook de ordem de pagamento usam o seguinte envelope:

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

O mesmo formato de data é usado em todos os eventos. Campos que não estão disponíveis na etapa atual podem ser null. Em particular, transactionId, amountFiatReceived e amountSettled podem não estar preenchidos no evento onramp.payment-order.created.

Evento	`data.status` esperado	Significado
`onramp.payment-order.created`	`pending` ou `processing`	A ordem de pagamento foi criada e está aguardando o pagamento.
`onramp.payment-order.paid`	`paid`	O pagamento e a liquidação foram concluídos com sucesso.
`onramp.payment-order.failed`	`failed`	Não foi possível concluir a ordem de pagamento.
`onramp.payment-order.cancelled`	`cancelled`	A ordem de pagamento foi cancelada.

Tratamento de eventos

Retorne uma resposta 2xx bem-sucedida assim que o evento for aceito.
Use data.id como o identificador da ordem de pagamento e torne o processamento idempotente.
Não presuma que os eventos chegam apenas uma vez ou em uma ordem específica.
Use event e data.status em conjunto ao atualizar a ordem no seu sistema.
Trate onramp.payment-order.paid como o evento final de sucesso.
Trate onramp.success como o evento final de sucesso da transação de onramp correspondente.

​Duas famílias de webhooks

​Eventos da ordem de pagamento

​onramp.payment-order.created

​onramp.payment-order.paid

​onramp.payment-order.failed

​onramp.payment-order.cancelled

​Payload

​Tratamento de eventos

Duas famílias de webhooks

Eventos da ordem de pagamento

`onramp.payment-order.created`

`onramp.payment-order.paid`

`onramp.payment-order.failed`

`onramp.payment-order.cancelled`

Payload

Tratamento de eventos