Payout
Quick Reference
O que é um payout
Um payout é o fluxo de saída — dinheiro deixando a plataforma, o inverso de uma cobrança. Em vez de coletar dinheiro de um pagador, você envia dinheiro de uma carteira para um beneficiário. Um único endpoint atende a todos os rails; o campo type_payout seleciona qual deles.
| Característica | Detalhe |
|---|---|
| Direção | Saída (disbursement) |
| Financiamento | Debitado de uma carteira (wallet_uuid) |
| Rails | PIX, TED, SPEI, transferência bancária LATAM, retirada em dinheiro |
| Mercados | Brasil, México e LATAM (Argentina, Chile, Colômbia, Peru, Equador, Guatemala, Honduras) |
| Idempotência | Por carteira via transaction_reference |
| Confirmação | Assíncrona via webhook |
Rails de payout
type_payout | Objeto de destino | Mercados típicos |
|---|---|---|
pix | pix_destination | Brasil |
ted | bank_destination | Brasil |
spei | bank_destination | México |
bank_transfer | bank_destination | LATAM |
cash_pickup | cash_destination | Equador e redes de cash |
Como funciona
Merchant cria o payout
Seu servidor chama POST /api/v1/bank/wallet/payout/ com wallet_uuid, type_payout, value, description e o objeto de destino correspondente.
A55 valida e roteia
A A55 valida o payload, verifica o saldo da carteira e roteia para um provider elegível.
Provider envia os fundos
O provider transfere os fundos para a conta do beneficiário (ou gera um código de retirada para payouts em dinheiro).
Webhook confirma o resultado
A A55 envia um webhook para sua webhook_url quando o payout chega a um status final (realized, returned, error, etc.).
Fluxo do payout
Ciclo de vida do payout
| Status | Descrição |
|---|---|
| pending | Criado, aguardando processamento |
| issued | Enviado ao provider |
| realized | Confirmado e liquidado |
| returned | Devolvido pelo banco receptor |
| canceled | Cancelado |
| error | Falhou no processamento |
| expired | Expirado |
A resposta síncrona retorna o status inicial. Um payout normalmente passa de issued para realized de forma assíncrona. Configure a webhook_url e confie no webhook para o resultado final.
Idempotência
Payouts são idempotentes por carteira via transaction_reference. Se você omitir, a A55 gera um. Reutilizar a mesma referência para a mesma carteira é rejeitado com errors.wallet.payout_already_exists, o que protege você de enviar um payout duplicado em retentativas.
Roteamento de provider e failover
A A55 seleciona um provider elegível para o rail e a moeda escolhidos com base em regras internas (capacidade, saldo e configuração da conta). Se o primeiro provider falha, o orquestrador pode tentar o próximo provider elegível automaticamente antes de marcar o payout como error.
Referência da API
Os schemas completos de request e response, códigos de erro e exemplos por rail estão na referência da API:
| Operação | Endpoint |
|---|---|
| Criar payout | POST /api/v1/bank/wallet/payout/ |
| Listar payouts | GET /api/v1/bank/wallet/payout/ |
| Consultar payout | GET /api/v1/bank/wallet/payout/{payout_uuid}/{wallet_uuid}/ |
| Webhook de payout | Notificação para sua webhook_url |