Status e ciclo de vida

Máquina de estados da cobrança e do saque: o que cada status significa e quais eventos são enviados.

Cobrança

Status	Significado	Evento
`pending`	Criada, aguardando o pagamento do PIX.	—
`paid`	Paga. O valor líquido está no saldo disponível.	`charge.paid`
`canceled`	Cancelada antes do pagamento.	—
`refunded`	Estornada ao pagador.	—
`failed`	Não foi possível gerar o PIX. O motivo vem em failureReason.	—

paid, canceled, refunded e failed são finais. Só paid gera webhook; os outros aparecem ao consultar ou listar a cobrança. failed acontece na criação, junto com a resposta 502 processing_failed.

Transições da cobrançaEstados

pending ──▶ paid
   │
   ├────▶ canceled
   ├────▶ refunded
   └────▶ failed

Saque

Status	Significado	Evento
`pending`	Em processamento. O valor está reservado no saldo.	—
`paid`	Chegou na chave PIX de destino.	`payout.paid`
`canceled`	Recusado ou cancelado depois de aceito. O valor voltou ao saldo disponível.	`payout.canceled`
`failed`	Recusado na criação, por saldo insuficiente ou dados recusados. Nada foi debitado.	—

Quando o processamento recusa o saque na criação, a API responde 502 processing_failed, o saque fica failed e um evento payout.canceled é enviado com o valor já devolvido.

Se o banco de destino devolver um saque pago, o saque continua paid e chega o evento payout.refunded com refundedAmountCents, já creditado no saldo disponível.

data em payout.refundedJSON

{
  "id": "a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31",
  "object": "payout",
  "status": "paid",
  "rail": "pix",
  "amountCents": 150000,
  "currency": "BRL",
  "pixKey": "financeiro@empresa.com.br",
  "pixKeyType": "EMAIL",
  "name": "Empresa Exemplo Ltda",
  "documentNumber": "11222333000181",
  "externalId": "repasse-2026-11",
  "metadata": {},
  "failureReason": null,
  "createdAt": "2026-11-02T18:20:00.000Z",
  "updatedAt": "2026-11-02T18:20:09.000Z",
  "refundedAmountCents": 150000
}

Transições do saqueEstados

pending ──▶ paid ··· payout.refunded
   │
   ├────▶ canceled
   └────▶ failed

Meio de saque

Saques saem por PIX, com rail: "pix". Qualquer outro valor é recusado.