As entidades representam os principais objetos de dados utilizados na comunicação com a API Pix. Elas definem a estrutura das informações que são enviadas e recebidas durante as operações de pedidos e pagamentos.
Cobrança (/cob)
Representa cada uma das cobranças geradas por meio da API Pix, a fim de permitir que o usuário pagador efetue um pagamento identificado para o usuário recebedor. A cobrança é caracterizada por um conjunto de informações que são utilizadas para que o usuário pagador execute um pagamento por meio do Pix, geralmente, em função de acordo comercial entre o usuário pagador e o usuário recebedor, sem se confundir com o pagamento Pix em si. O modelo de cobrança utilizado é para pagamento imediato.
Estados da cobrança:
- ATIVA: indica que a cobrança foi gerada e pronta para ser paga;
- CONCLUÍDA:: indica que a cobrança já foi paga e, por conseguinte, não pode acolher outro pagamento67;
- REMOVIDO_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção da cobrança; e
- REMOVIDO_PELO_PSP: indica que o PSP Recebedor solicitou a remoção da cobrança.
Pix (/pix)
Representa um pagamento recebido por meio do arranjo de pagamentos Pix.
Devolução (devolução)
Representa uma solicitação de devolução de um Pix realizado, cujos fundos já se encontrem disponíveis na conta transacional do usuário recebedor.
Estados da devolução:
- EM_PROCESSAMENTO: indica que a devolução foi solicitada, mas ainda está em processamento no SPI;
- DEVOLVIDO: indica que a devolução foi liquidada pelo SPI; e
- NAO_REALIZADO: indica que a devolução não pode ser realizada em função de algum erro durante a liquidação (exemplo: saldo insuficiente).
Cardinalidade entre as entidades
- Uma Cobrança pode estar associada a um ou mais Pix (mesmo txid);
- Um Pix pode estar associado a uma única Cobrança. O Pix, no entanto, pode existir independentemente da existência de uma Cobrança;
- Um Pix pode ter uma ou mais Devoluções associadas a ele. Uma Devolução está sempre associada a um Pix.
- Uma Cobrança somente pode estar associada a um PayloadLocation e, num determinado momento, o PayloadLocation só pode estar associado a uma cobrança.