Campos centrais
| Campo | Quem define | Uso |
|---|---|---|
id | Plataforma (UUID) | Chave primária em consultas e em POST /api/pix/refund-in/{id} — é o UUID do cash-in, não o identificador do parceiro. |
externalId | Integrador | Idempotência e correlação com ERP/pedido. Deve ser único por operação quando a API assim exigir. |
transactionId | Parceiro (BaaS) | ID da transação no BaaS; informativo e usado em webhooks. |
endToEndId | Pix (BACEN) | Identificador fim a fim após liquidação. |
Regras de refund (crítico)
Para devolver um recebimento, o path é:POST /api/pix/refund-in/{id}
onde {id} é o id (UUID) do cash-in retornado em POST /api/pix/cash-in, não o transactionId do parceiro.
Para consultar um refund-in após a criação, use o UUID do refund em GET /api/pix/refund/{id} (ver documentação de detalhe).
O que persistir (recomendação operacional)
- Sempre o
id(UUID) retornado no201de cada recurso. - O
externalIdque você enviou (cópia de negócio). transactionIdeendToEndIdquando retornados ou presentes no webhook, para rastreio e conciliação com o parceiro.- Em devoluções parciais, o
iddo refund-in (via201derefund-inouGETde lista) para auditoria e deduplicação de eventos de estorno.
Implicações
| Tema | Detalhe |
|---|---|
| Rastreabilidade | Suporte e análise de incidente pedem, em geral, id da plataforma e, quando existir, endToEndId. |
| Webhook de estorno | Em pix_cash_in_reversal, a semântica de event.id e event.external_id difere de pix_cash_in (ver referência de eventos). |
| Reversão de cash-out | O webhook pix_cash_out_reversal carrega o UUID do cash-out em event.id (não do refund-in, pois o fluxo é outro). |