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

> Receba atualizações de status das ordens de pagamento do Depósito em Fiat.

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.

<Info>
  Consulte o [guia de Webhooks](/pt/utilities/webhooks) para configuração de
  endpoints, verificação de assinatura, novas tentativas e solução de problemas de entrega.
</Info>

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

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

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.


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