S
Stater

PIX saída

Payouts PIX

Envie PIX de uma subconta diretamente ou via fluxo em duas etapas (criar + aprovar).

Idempotency-Key obrigatório

Toda requisição de payout (direto, criação para aprovação, e aprovação) exige o cabeçalho Idempotency-Key. Use um UUID único por operação lógica.

Payout direto (débito + envio)

POST/v1/accounts/:accountId/pix/payouts
Body
amountintegerrequired

Valor em centavos, positivo.

destinationKeystringrequired

Chave PIX do destinatário.

descriptionstringoptional

Vira tag no provedor.

Erros possíveis

400 missing_idempotency_key

409 duplicated_reference — chave já usada com payload diferente.

422 insufficient_balance · account_not_virtual · account_missing_provider_fields

Em duas etapas

1. Criar para aprovação

POST/v1/accounts/:accountId/pix/payouts/for-approval

Mesmo body do direto. Resposta inclui recipientPreview (dados mascarados do destinatário). Idempotência retorna 200 com snapshot existente quando ainda AWAITING_APPROVAL.

2. Aprovar e liquidar

POST/v1/accounts/:accountId/pix/payouts/:payoutId/approve

Retorna 200 com payout atualizado (geralmente SUCCEEDED).

404 not_found · 422 payout_not_awaiting_approval · payout_invalid_state · insufficient_balance

Obter payout

GET/v1/accounts/:accountId/pix/payouts/:payoutId

Escopo: pix:out.

Comprovante (com movimento contábil)

GET/v1/accounts/:accountId/pix/payouts/:payoutId/receipt

Inclui o objeto movement (referência, tipo, metadata) quando existir.