Pré-aprovação

Como funciona

A pré-aprovação separa o pedido do pagamento: você cria o saque, a plataforma reserva o saldo e o Pix só sai quando você aprovar. Serve para fluxos com conferência humana ou com aprovação de um segundo sistema.

Fluxo

Crie a pré-aprovação com o valor e a chave. Ela nasce pending e o valor (com a taxa) é reservado na carteira, se houver saldo.
Confira do seu lado e aprove: o Pix é enviado e a resposta traz o saque criado.
Ou cancele: o valor reservado volta ao saldo disponível.

POST/pre-approvalsCria a pré-aprovação e tenta reservar o saldo.
POST/pre-approvals/{id}/approveAprova e envia o Pix.
POST/pre-approvals/{id}/cancelCancela e devolve o saldo reservado.
GET/pre-approvalsLista as pré-aprovações.
GET/pre-approvals/{id}Consulta uma pré-aprovação pelo id.

Status

pending: Aguardando aprovação (com ou sem o saldo reservado).
approved: Aprovada e Pix enviado. O saque tem pre_approval_id com o id dela.
failed: O envio falhou; o valor reservado volta ao saldo.
rejected: Cancelada por você.

Regras

Idempotência obrigatória: envie reference no corpo ou o header Idempotency-Key. Repetir a mesma responde 409 duplicate_reference com a pré-aprovação existente em pre_approval.
Reserva condicional: a pré-aprovação é criada mesmo sem saldo suficiente. Nesse caso a reserva é tentada de novo na aprovação, e a aprovação falha com 422 se ainda faltar saldo.
Falha devolve: se o envio falhar, o valor reservado é liberado automaticamente.
Webhooks: cada etapa gera um evento pre_approval.created, approved, rejected ou failed. Veja Eventos e payloads.