Transações

Ciclo de vida de cash-ins e cash-outs

Cash-in (recebimento)

Estados:

Status	Final?	Significado
pending	❌	QR Code gerado, aguardando pagamento.
paid	✅	Cliente pagou. Saldo creditado.
expired	✅	QR Code expirou sem pagamento.
refunded	✅	Devolução pós-pagamento. Saldo estornado.

Cash-out (pagamento)

Estados:

Status	Final?	Significado
processing	❌	Pagamento enviado, aguardando confirmação do banco do destinatário.
paid	✅	Banco confirmou. Pagamento concluído.
refunded	✅	Não foi possível concluir (ex: chave inválida no banco do destinatário). Saldo é estornado automaticamente.
failed	✅	Rejeitado na validação inicial (saldo insuficiente, dados inválidos). Nenhum valor é movimentado.

Idempotência

Use external_id como identificador único da sua transação. Se você enviar a mesma cobrança 2x com o mesmo external_id:

• Se a primeira ainda está pending/processing/paid → retornamos erro 409 Conflict (ou 401 com mensagem específica em endpoints legados).
• Se a primeira está failed → permitimos retentar com mesmo external_id.

Use UUIDs ou IDs únicos do seu sistema (pedido-001, withdrawal-abc123) — nunca timestamps puros (que podem colidir em alta concorrência).