pacs.004 de saída antes de enviá-lo, e uma falha de registro não bloqueia necessariamente o despacho. As operações retornam um estado aceito-mas-não-liquidado e reconciliam contra a resposta assíncrona do BACEN.
Habilitação e prontidão
Você cadastra um participante pelo seu ISPB. Um participante indireto entra em
PENDING; o trilho envia sua solicitação de cadastro, e somente a confirmação do BACEN pode ativá-lo. A ação de ativação apenas reativa um participante já suspenso. O trilho executa a prontidão em uma ordem obrigatória. Um teste de conectividade aprovado é o pré-requisito para um envio.
- Envie um certificado Pix — apenas o
.cerpúblico. O trilho recusa uma chave privada enviada. - Confirme que o trilho reporta que está pronto.
- Passe por um teste de conectividade.
- Você já pode enviar pagamentos.
Enviar um Pix
Você cria uma ordem de pagamento. A plataforma monta a mensagem ISO 20022 de transferência de crédito (
pacs.008), persiste a operação e a despacha. O BACEN retorna um callback de status assíncrono (pacs.002). O trilho o valida e o aplica, e depois move o pagamento para completed ou rejected. Você lê um pagamento pelo seu end-to-end ID, com o seu histórico e uma linha do tempo por operação.
Receber um Pix
O consumidor ICOM recebe mensagens assinadas do BACEN e as encaminha para a entrada interna autenticada do trilho. Para um
pacs.008 recebido, o trilho valida a mensagem e registra o Pix como pendente. Em seguida, o cliente fornece a decisão de funding para esse Pix já recebido. Um pagamento de saída não pode receber funding como dinheiro de entrada. Os participantes listam os Pix que recebem.
Devolução
Você inicia uma devolução (
pacs.004) apenas para um Pix liquidado que o trilho recebeu do BACEN e depois lê seu status. A devolução debita o recebedor original e credita o pagador original. Você não pode iniciar uma devolução para um Pix que seu cliente enviou; a contraparte emite a devolução desse Pix, que chega ao trilho como mensagem de entrada. Uma devolução é o caminho de movimentação de dinheiro do MED — a forma como os fundos voltam a um pagador por uma disputa concluída ou um erro.
Existem duas superfícies de devolução, e o trilho registra qual delas criou cada devolução em vez de inferir isso depois. Uma devolução integral reverte o Pix inteiro e move o pagamento pai para fora de completed. Uma devolução parcial é chaveada pelo devolucaoId que você escolhe e nunca move o pagamento pai. Várias devoluções parciais podem coexistir para um mesmo Pix.
Três travas se aplicam a toda devolução, nas duas superfícies:
- O pagamento pai precisa ser um Pix de entrada que liquidou. Só um pagamento recebido que chegou a
completed— ou que já carrega uma devolução — pode ser devolvido. - A janela de devolução do BACEN. Uma devolução precisa ser solicitada em até 90 dias da liquidação original do Pix, e o trilho mede a janela a partir do instante da liquidação, nunca a partir da criação ou da última atualização. Um Pix sem instante de liquidação registrado não é bloqueado: o trilho registra a lacuna e encaminha a solicitação.
- O teto da soma. A soma dos valores de todas as devoluções de um Pix não pode ultrapassar o valor daquele Pix. O trilho lê apenas o valor daquele pagamento e as devoluções dele; não calcula posição alguma entre pagamentos.
EM_PROCESSAMENTO e chega a DEVOLVIDO ou NAO_REALIZADO somente com a resposta do BACEN — um aceite de transporte não é uma conclusão. Uma devolução que falha libera o teto que estava segurando, e uma devolução integral que falha devolve o pagamento pai para completed sem rearmar a janela de 90 dias.
Você solicita uma devolução como ORIGINAL (o padrão quando você não envia natureza) ou RETIRADA, a perna de Pix Saque e troco. As duas naturezas de MED — falha operacional e suspeita de fraude fundamentada — existem apenas do lado da resposta: elas decorrem do motivo que o trilho coloca no pacs.004, e você nunca as pede.
Ciclo de vida das chaves DICT
Você gerencia as chaves Pix diretamente contra o diretório DICT: registrar, listar, buscar, consultar, atualizar e excluir uma chave. Você também verifica em lote se um conjunto de chaves existe. O trilho lê as estatísticas de chaves do DICT e as estatísticas antifraude do BACEN, tanto por chave quanto por pessoa.
Reivindicações do DICT
Uma reivindicação move uma chave Pix entre participantes por portabilidade ou titularidade. Você inicia uma reivindicação contra um participante e depois a move pelo seu ciclo de vida. O ciclo de vida abrange acknowledge, confirmar ou rejeitar, e completar ou cancelar, entre os lados doador e reivindicante. Quando
SCHEDULER_ENABLED=true e SCHEDULER_CLAIM_DEADLINE_ENABLED=true, o trilho registra o processamento periódico dos prazos de reivindicações. Ele tenta avançar as reivindicações conforme as janelas do BACEN, mas uma reivindicação ainda pode exigir atenção.
BR Code e cobranças
Um QR dinâmico resolve para uma cobrança persistida, então você cria a cobrança primeiro e depois gera o payload que resolve para ela. Um QR estático é gerado a partir de dados estáticos de pagamento; ele não exige nem aponta para uma cobrança.
- Crie uma cobrança: Cob (imediata), CobV (com vencimento, com juros e multa) ou um lote de cobranças com vencimento.
- Gere o payload QR EMV dinâmico, que se liga à cobrança pelo seu txid ou localizador e resolve como um JWS assinado.
Pix Automático (recorrente)
O Pix Automático autoriza pagamentos recorrentes e agendados por meio da família recorrente do ISO 20022:
- Crie uma autorização recorrente (recorrência) ou uma solicitação de recorrência.
- Solicite a confirmação do mandato (
pain.009), cancele-o (pain.011) ou aceite / rejeite (pain.012). - Agende uma instrução (
pain.013) e aceite / rejeite (pain.014). - Solicite o cancelamento de uma instrução agendada (
camt.055) e resolva um cancelamento recebido (camt.029). - Solicite uma retentativa de liquidação quando uma cobrança agendada falha.
Disputas MED
A superfície MED (Mecanismo Especial de Devolução) trata casos de fraude e erro de ponta a ponta:
- Abra um caso MED, analise-o e depois resolva-o, feche-o ou cancele-o com evidência anexada.
- Registre relatos de infração, solicitações de devolução, marcações de fraude e pedidos de recuperação de fundos do DICT, cada um rastreado ao longo do seu grafo de ciclo de vida.
- Reporte os Pix liquidados internamente por meio do relatório de liquidação do MED 2.0.
Reporte da Conta PI
Você solicita um relatório de conta (
camt.060) e depois lê o saldo (camt.053), o extrato (camt.052) ou o detalhe de lançamentos (camt.054) que o BACEN retorna. Os relatórios síncronos de volumetria (apenas contagem), pagamentos rejeitados, saldo e extrato completam a superfície de reporte, cada um restrito ao seu período de referência.