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

# Eventos

> Catálogo de eventos de webhook e seus payloads.

## Lista de eventos

| Evento                   | Tipo           | Quando                                                     |
| ------------------------ | -------------- | ---------------------------------------------------------- |
| `order.payment_received` | PAYIN          | PIX recebido; conversão em andamento                       |
| `order.processing`       | PAYOUT         | Depósito aceito; PIX de saída em andamento                 |
| `order.deposit_received` | PAYOUT         | Depósito de cripto detectado on-chain                      |
| `order.pix_sending`      | PAYOUT         | PIX de saída submetido à 3xPay                             |
| `order.completed`        | PAYIN / PAYOUT | Ordem concluída com sucesso                                |
| `order.failed`           | PAYIN / PAYOUT | Ordem falhou; inclui `failureReason`                       |
| `order.refunding`        | PAYIN          | Payin falhou após PIX recebido — reembolso iniciado        |
| `order.refunded`         | PAYIN          | Reembolso PIX concluído com sucesso                        |
| `receiver.kyc_approved`  | RECEIVER       | KYC do receiver foi aprovado pelo admin                    |
| `receiver.kyc_rejected`  | RECEIVER       | KYC do receiver foi rejeitado; inclui `kycRejectionReason` |

## Formato padrão

Os campos são enviados no nível raiz do payload (não dentro de um objeto `data`). Todo evento inclui:

```json theme={null}
{
  "event": "order.completed",
  "orderId": "ord_uuid",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "COMPLETED",
  "timestamp": "2026-04-16T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

Os campos adicionais variam por evento (documentados abaixo).

## Exemplos

### `order.payment_received`

Disparado quando o PIX do cliente é confirmado e a conversão foi enfileirada.

```json theme={null}
{
  "event": "order.payment_received",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "PAYMENT_RECEIVED",
  "amountBrl": 1000,
  "pixEndToEndId": "E00000000202604161831...",
  "timestamp": "2026-04-16T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.completed` — PAYIN

Disparado quando a transferência on-chain de cripto para o receiver é confirmada.

```json theme={null}
{
  "event": "order.completed",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amountBrl": 1000,
  "amountToken": 199.5,
  "targetToken": "USDC",
  "destinationWallet": "So1Endereco...",
  "txHash": "5KJp3xRk...",
  "timestamp": "2026-04-16T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.completed` — PAYOUT

Disparado quando o PIX de saída é confirmado como recebido.

```json theme={null}
{
  "event": "order.completed",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYOUT",
  "status": "COMPLETED",
  "amountBrl": 4500,
  "pixKey": "11999999999",
  "pixEndToEndId": "E00000000202604161900...",
  "timestamp": "2026-04-16T19:00:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.deposit_received`

Disparado quando o depósito de cripto do merchant é detectado on-chain (payout).

```json theme={null}
{
  "event": "order.deposit_received",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYOUT",
  "status": "DEPOSIT_RECEIVED",
  "amountCrypto": 500,
  "txHash": "5KJp3xRk...",
  "timestamp": "2026-04-16T18:45:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.processing`

Disparado quando o payout tem depósito aceito e o PIX de saída foi enfileirado.

```json theme={null}
{
  "event": "order.processing",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYOUT",
  "status": "PIX_SENDING",
  "amountBrl": 4500,
  "pixKey": "11999999999",
  "timestamp": "2026-04-16T18:50:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.pix_sending`

Disparado quando o PIX de saída foi submetido ao provedor de pagamentos.

```json theme={null}
{
  "event": "order.pix_sending",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYOUT",
  "status": "PIX_SENDING",
  "amountBrl": 4500,
  "pixKey": "11999999999",
  "threexpayTransactionId": "txn_abc123",
  "timestamp": "2026-04-16T18:52:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.failed`

```json theme={null}
{
  "event": "order.failed",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "FAILED",
  "failureReason": "Insufficient platform USDC balance",
  "timestamp": "2026-04-16T18:35:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.refunding`

Disparado quando um payin falhou **após o PIX ser recebido** — reembolso PIX iniciado automaticamente.

<Note>
  Este evento é exclusivo de payins. A plataforma automaticamente estorna o PIX ao receiver.
</Note>

```json theme={null}
{
  "event": "order.refunding",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "REFUNDING",
  "failureReason": "On-chain transfer failed after 5 attempts",
  "timestamp": "2026-04-16T18:40:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `order.refunded`

```json theme={null}
{
  "event": "order.refunded",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "REFUNDED",
  "amountBrl": 1000,
  "timestamp": "2026-04-16T18:45:00.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `receiver.kyc_approved`

Disparado quando um admin aprova o KYC de um receiver. Use para liberar fluxos
no seu lado (notificar o usuário final, habilitar criação de orders, etc).

```json theme={null}
{
  "event": "receiver.kyc_approved",
  "receiverId": "rcv_01hxy...",
  "type": "PF",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "kycStatus": "APPROVED",
  "kycReviewedAt": "2026-04-27T18:31:12.000Z",
  "timestamp": "2026-04-27T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

### `receiver.kyc_rejected`

Disparado quando um admin rejeita o KYC. O `kycRejectionReason` é a mensagem
visível ao receiver na próxima tentativa de submissão.

```json theme={null}
{
  "event": "receiver.kyc_rejected",
  "receiverId": "rcv_01hxy...",
  "type": "PF",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "kycStatus": "REJECTED",
  "kycRejectionReason": "Documento ilegível",
  "kycReviewedAt": "2026-04-27T18:31:12.000Z",
  "timestamp": "2026-04-27T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}
```

## Obtendo via API

Lista canônica (pode estar à frente desta documentação):

```bash theme={null}
curl https://api.astronpay.co/api/v1/webhook/events \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```