Eventos

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:

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

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

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

{
  "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).

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

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

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

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

Este evento é exclusivo de payins. A plataforma automaticamente estorna o PIX ao receiver.

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

{
  "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).

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

{
  "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):

curl https://api.astronpay.co/api/v1/webhook/events \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"

Introdução

Conceitos

Guias

Webhooks recebidos

Lista de eventos

Formato padrão

Exemplos

`order.payment_received`

`order.completed` — PAYIN

`order.completed` — PAYOUT

`order.deposit_received`

`order.processing`

`order.pix_sending`

`order.failed`

`order.refunding`

`order.refunded`

`receiver.kyc_approved`

`receiver.kyc_rejected`

Obtendo via API

​Lista de eventos

​Formato padrão

​Exemplos

​order.payment_received

​order.completed — PAYIN

​order.completed — PAYOUT

​order.deposit_received

​order.processing

​order.pix_sending

​order.failed

​order.refunding

​order.refunded

​receiver.kyc_approved

​receiver.kyc_rejected

​Obtendo via API

Lista de eventos

Formato padrão

Exemplos

`order.payment_received`

`order.completed` — PAYIN

`order.completed` — PAYOUT

`order.deposit_received`

`order.processing`

`order.pix_sending`

`order.failed`

`order.refunding`

`order.refunded`

`receiver.kyc_approved`

`receiver.kyc_rejected`

Obtendo via API