Webhooks de Transferência
Webhooks de transferência notificam sua aplicação sobre mudanças de status em transferências Pix Out em tempo real.
Estrutura do payload (envelope)
O payload segue um formato inspirado no Stripe, com um envelope contendo metadados e um objeto data com os detalhes da transferência.
{
"id": "evt_019505a2-7c3e-7000-8a1b-3f9d2e1c4b5a",
"type": "payout.created",
"created": 1738958400,
"api_version": "v2",
"data": {
"object": {
"id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
"status": "pending",
"type": "pix",
"amount": 10100,
"fee": 100,
"net_amount": 10000,
"description": "Pagamento fornecedor",
"pix_key_type": "CPF",
"recipient": {
"legal_name": "J*** S****",
"document": "***.***.***-90"
},
"transferred_at": null,
"created_at": "2026-02-07T18:00:00.000Z"
}
}
}
Campos do envelope
| Campo | Tipo | Descrição |
|---|
id | string | ID único do evento de webhook |
type | string | Tipo do evento (ex: payout.created) |
created | number | Timestamp Unix (segundos) da criação do evento |
api_version | string | Versão da API (v2) |
data.object | object | Dados da transferência |
Campos de data.object
| Campo | Tipo | Descrição |
|---|
id | string | ID público da transferência |
status | string | Status externo da transferência |
type | string | Tipo da transferência (ex: pix) |
amount | number | Valor total em centavos (valor líquido + taxa) |
fee | number | Taxa da operação em centavos |
net_amount | number | Valor líquido em centavos |
description | string|null | Descrição da transferência |
pix_key_type | string|null | Tipo da chave Pix (CPF, CNPJ, EMAIL, PHONE, EVP) |
recipient.legal_name | string | Nome do destinatário (mascarado) |
recipient.document | string | Documento do destinatário (mascarado) |
transferred_at | string|null | Data/hora da efetivação (ISO 8601) |
created_at | string | Data/hora de criação (ISO 8601) |
Dados sensíveis como nome e documento do destinatário são mascarados no webhook por segurança.
Tipos de evento
| Evento | Status | Descrição |
|---|
payout.created | pending | Transferência criada, aguardando processamento |
payout.in_analysis | in_analysis | Em análise pelo provedor |
payout.processing | processing | Sendo processada pelo provedor |
payout.transferred | paid | Transferência concluída com sucesso |
payout.failed | error | Falha no processamento (reportar ao suporte para reconciliação; pode ser atualizado para cancelled ou paid se o envio tiver sido efetivado) |
payout.rejected | rejected | Rejeitada pelo provedor |
payout.canceled | cancelled | Cancelada ou estornada |
Boas práticas
- Responder
200 OK rapidamente - retorne o status antes de processar o evento
- Processar de forma assíncrona - use filas ou workers para lógica pesada
- Idempotência - deduplicar por
id do evento + data.object.id da transferência
- Registrar logs - inclua
id e type do evento nos logs para rastreabilidade
Evite polling contínuo. Use webhooks como fonte principal de atualização e GET /v2/transfers/{id} como fallback para reconciliação.
