pacs.004 de saída antes de despachá-lo. Uma falha no registro não bloqueia necessariamente o despacho. As operações retornam um estado de aceito-mas-não-liquidado e se reconciliam com a resposta assíncrona do BACEN.
Onboarding e prontidão
Você registra um participante pelo seu ISPB. Um participante indireto entra como
PENDING. O trilho envia a solicitação de registro, e apenas a confirmação do BACEN pode torná-lo ativo. 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.
- Faça upload de um certificado Pix, apenas o
.cerpúblico. O trilho rejeita uma chave privada enviada. - Confirme que o trilho reporta pronto.
- Passe em um teste de conectividade.
- Agora você pode enviar pagamentos.
Enviar um Pix
Você cria uma ordem de pagamento. A plataforma monta a mensagem de transferência de crédito ISO 20022 (
pacs.008), persiste a operação e a despacha. O BACEN retorna um callback de status assíncrono (pacs.002). O trilho valida e aplica o callback, então move o pagamento para completed ou rejected. Você consulta um pagamento pelo seu ID fim a fim, com seu histórico e uma linha do tempo por operação.
Receber um Pix
O consumidor ICOM recebe mensagens assinadas do BACEN e as repassa para a ingestão interna autenticada do trilho. Para um
pacs.008 de entrada, o trilho valida a mensagem e registra o Pix como pendente. O cliente então fornece a decisão de financiamento para esse Pix já recebido. Um pagamento de saída não pode receber financiamento 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 consulta o status da devolução. 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 uma devolução desse Pix, e ela chega ao trilho como uma mensagem de entrada. Uma devolução é o caminho de movimentação de dinheiro do MED, a forma como os fundos retornam a um pagador em uma disputa concluída ou erro.
Existem duas superfícies de devolução, e o trilho registra qual delas criou uma devolução em vez de inferir isso depois. Uma devolução total reverte o Pix inteiro e move o pagamento pai para fora de completed. Uma devolução parcial usa o devolucaoId que você escolhe como chave e nunca move o pagamento pai. Várias devoluções parciais podem coexistir para um mesmo Pix.
Três validações se aplicam a toda devolução, nas duas superfícies:
- O pai deve ser um Pix de entrada que liquidou. Apenas 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 deve ser solicitada em até 90 dias da liquidação do Pix original. O trilho mede a janela a partir do instante de liquidação, nunca da criação ou da última atualização. Um Pix sem instante de liquidação registrado não fica bloqueado: o trilho registra a lacuna e encaminha a solicitação.
- O teto de soma. Os valores de todas as devoluções de um Pix não podem exceder o valor do próprio Pix. O trilho lê apenas o valor daquele pagamento e suas próprias devoluções. Não computa nenhuma posição entre pagamentos.
EM_PROCESSAMENTO e chega a DEVOLVIDO ou NAO_REALIZADO apenas com a resposta do BACEN. Uma aceitação de transporte não é uma conclusão. Uma devolução que falha libera o teto que ocupava. Uma devolução total que falha retorna o pagamento pai para completed sem reativar sua janela de 90 dias.
Você solicita uma devolução como ORIGINAL (o padrão quando você não envia nenhuma natureza) ou RETIRADA, a etapa de Pix Saque e troco. As duas naturezas do MED (falha operacional e suspeita fundada de fraude) existem apenas do lado da resposta. Elas decorrem do motivo que o trilho coloca no pacs.004, e você nunca as solicita.
Ciclo de vida da chave DICT
Você gerencia chaves Pix diretamente no diretório DICT: registrar, listar, pesquisar, consultar, atualizar e excluir uma chave. Você também verifica em lote se um conjunto de chaves existe. O trilho lê estatísticas de chave do DICT e 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 posse. Você inicia uma reivindicação contra um participante e depois a avança pelo seu ciclo de vida. O ciclo de vida abrange reconhecer, confirmar ou rejeitar, e concluir ou cancelar, nos lados do doador e do reivindicante. Quando tanto
SCHEDULER_ENABLED=true quanto SCHEDULER_CLAIM_DEADLINE_ENABLED=true estão definidos, o trilho registra o processamento periódico de prazo de reivindicação. Ele tenta avançar reivindicações dentro das 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 a ela. Um QR estático é gerado a partir de dados de pagamento estáticos. 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 do QR EMV dinâmico, que vincula à 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 ISO 20022 de recorrência:
- Crie uma autorização recorrente (recorrência) ou uma solicitação para uma.
- Solicite a confirmação do mandato (
pain.009), cancele-o (pain.011), ou aceite / rejeite-o (pain.012). - Agende uma instrução (
pain.013) e aceite / rejeite-a (pain.014). - Solicite o cancelamento de uma instrução agendada (
camt.055) e resolva um cancelamento recebido (camt.029). - Solicite uma nova tentativa de liquidação (retentativa) quando uma cobrança agendada falha.
Disputas MED
A superfície do MED (Mecanismo Especial de Devolução) trata casos de fraude e erro:
- Abra um caso MED, analise-o, depois resolva, feche ou cancele-o com evidências anexadas.
- Registre relatórios de infração do DICT, solicitações de reembolso, marcadores de fraude e solicitações de recuperação de fundos, cada um rastreado por seu grafo de ciclo de vida.
- Reporte Pix liquidados internamente por meio do relatório de liquidação do MED 2.0.
Relatórios da Conta PI
Você solicita um relatório de conta (
camt.060), depois lê o saldo (camt.053), o extrato (camt.052) ou o detalhe de lançamento (camt.054) que o BACEN retorna. Relatórios síncronos e apenas de contagem de volumetria, pagamentos rejeitados, saldo e extrato completam a superfície de relatórios, cada um limitado ao seu período de referência.