Pular para o conteúdo principal
O Lerian SPI expõe a superfície de mensagens do Pix como um conjunto de operações tipadas. O trilho envia as mensagens destas operações como seu participante direto, o ISPB em BACEN_SPI_PARTICIPANT_ISPB:
  • o teste de conectividade;
  • a solicitação de relatório da Conta PI e o registro dos responsáveis;
  • a solicitação, o cancelamento e a resolução de mandato do Pix Automático (pain.009, pain.011, pain.012);
  • a instrução, a resolução e o cancelamento de agendamento do Pix Automático (pain.013, pain.014, camt.055);
  • o relatório de liquidação do MED 2.0.
Os corpos de requisição dessas operações não recebem participantIspb, e um corpo que o traz recebe 422.

​
Onboarding e prontidão

Você registra um participante indireto pelo seu ISPB. Ele entra como PENDING, e o trilho envia a solicitação de registro. Apenas a confirmação do BACEN o torna ACTIVE. Uma recusa do BACEN o torna REGISTRATION_REJECTED. A ação de ativação apenas reativa um participante SUSPENDED. A ordem de preparação recomendada antes de enviar pagamentos é:
  1. Faça upload de um certificado Pix, apenas o .cer público. O trilho rejeita uma chave privada enviada.
  2. Confirme que o trilho reporta pronto.
  3. Passe em um teste de conectividade.
  4. Envie pagamentos.
A mesma superfície Core também suspende e encerra um participante ao longo do seu ciclo de vida. O encerramento de um participante direto o torna OFFBOARDED na hora. O encerramento de um participante indireto o move para OFFBOARD_PENDING, e o trilho envia ao BACEN um reda.031. A resposta reda.016 do BACEN torna o participante OFFBOARDED, ou ACTIVE de novo se o BACEN recusar. Enquanto o reda.031 aguarda essa resposta, uma nova solicitação de encerramento recebe 409. Quando o trilho sabe que o reda.031 não chegou ao BACEN, você pode enviar a solicitação de encerramento de novo.

​
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 uma resposta de status assíncrona (pacs.002). O trilho valida e aplica a resposta, 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. Quando o trilho não consegue se conectar ao BACEN e não envia nada, o pagamento termina como FAILED, e a requisição recebe 503 com o código SPI-1001. Uma devolução no mesmo caso termina como NAO_REALIZADO, com a mesma resposta. Uma operação que precisa de atenção aparece na lista de operações travadas, com as ações que ela aceita. Você envia uma ação com um motivo. A resolução manual encerra uma operação travada. Ela exige uma aprovação APPROVED para essa operação. Para um Pix enviado que o BACEN não respondeu, a resolução declara o resultado em outcome: SETTLED ou REJECTED. A aprovação nomeia o mesmo resultado em requestedAction: MANUAL_RESOLVE_SETTLED ou MANUAL_RESOLVE_REJECTED. Uma declaração SETTLED também traz o instante de liquidação do BACEN tirado da evidência, em settledAt. O trilho encerra o Pix como faz um pacs.002 e publica spi_payment.settled ou spi_payment.rejected. Uma resposta posterior do BACEN não muda o Pix. Quando o BACEN não responde a um Pix enviado dentro do prazo, a linha dele oferece RECONCILE_WITH_BACEN. Com essa ação, o trilho pede ao BACEN o lançamento do pagamento (camt.060). Quando a resposta camt.054 do BACEN informa o pagamento como liquidado ou rejeitado, o trilho o conclui ou o rejeita, como faz um pacs.002. Qualquer outra resposta deixa o pagamento aberto.

​
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 PENDING. Seu cliente então decide esse Pix de uma de três formas. Ele envia evidência de fundos (saldo disponível, limite disponível, score de risco) para o trilho avaliar, declara que já autorizou o crédito ou envia um motivo de recusa. O trilho responde uma recusa FRAD como FRAD apenas quando seu cliente a marca como decisão do sistema antifraude dele. Sem a marca, o trilho responde DS04. O trilho responde ao SPI sobre um Pix aceito, e o Pix chega a COMPLETED apenas quando o SPI confirma o crédito, ou a REJECTED se o SPI o recusar. O trilho recusa um Pix que nenhuma decisão conclui dentro da sua janela regulatória, e uma decisão posterior recebe 409. Um pagamento de saída não pode receber financiamento como dinheiro de entrada. Você lista os Pix que recebe e os Pix que ainda aguardam uma decisão. O evento spi_payment.received traz o fim da janela regulatória em decisionDeadline. Um Pix Agendado (PAGAGD) tem 45 minutos e um Pix com suspeita de fraude (PAGFRD) tem 40 segundos, ambos a partir do recebimento pelo SPI. Qualquer outro Pix tem 40 segundos a partir do momento em que a instituição do pagador aceitou a ordem. O trilho reserva os últimos 6 segundos de cada janela para o trabalho após a decisão.

​
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. Uma devolução de entrada não é liquidada na chegada. O trilho a retém e a anuncia em um evento studio.lerian.br-spi.spi_payment.return_received que carrega o returnId dela. Seu cliente decide a devolução por esse returnId: ele autoriza a devolução ou a recusa com um motivo. Uma devolução autorizada é liquidada apenas quando o SPI a confirma. O trilho recusa uma devolução que nenhuma decisão conclui dentro da sua janela, e uma decisão posterior recebe 409. Existem duas superfícies de devolução, a solicitação de devolução e a devolução de pagamento. O trilho registra qual delas criou uma devolução em vez de inferir isso depois. Uma solicitação de devolução é sempre parcial, qualquer que seja o valor, e usa o devolucaoId que você escolhe como chave. Uma devolução de pagamento de valor menor que o do Pix também é parcial e exige um devolucaoId. Uma devolução de pagamento do valor inteiro é total: ela reverte o Pix inteiro e move o pagamento pai para fora de COMPLETED. Uma devolução parcial mantém o pagamento pai liquidado, e várias devoluções parciais podem coexistir para um mesmo Pix. Quando as devoluções parciais liquidadas alcançam o valor do Pix, o pagamento pai passa para RETURNED. 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. Uma devolução que termina em NAO_REALIZADO não conta. O trilho lê apenas o valor daquele pagamento e suas próprias devoluções. Não computa nenhuma posição entre pagamentos.
Uma aceitação de transporte não é uma conclusão. Uma solicitação de devolução aceita a natureza ORIGINAL (o padrão quando você não envia nenhuma) ou RETIRADA, a etapa de Pix Saque e troco. Uma devolução de pagamento aceita um motivo: MD06, SL02, BE08 ou FR01. As duas naturezas do MED (falha operacional e suspeita fundada de fraude) decorrem de BE08 e FR01. Você nunca as solicita como natureza.

​
Ciclo de vida da chave DICT

Você registra, atualiza e exclui chaves Pix no diretório DICT. Você também lista, pesquisa e consulta chaves, e 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. Para a sincronização do diretório, o trilho expõe as operações VSync do BACEN. Ele verifica um conjunto de CIDs, resolve um CID e lista os eventos do conjunto de CIDs. Ele também solicita e transmite um arquivo do conjunto de CIDs.

​
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. O job de prazo de reivindicação roda por padrão e avança as reivindicações dentro das janelas do BACEN. Uma reivindicação ainda pode exigir atenção. Você pode abandonar uma reivindicação aberta que o BACEN nunca registrou. A reivindicação termina em CANCELLED, e o trilho não envia nada ao BACEN.

​
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.
Você também gera um QR estático, decodifica um payload, valida-o e registra um perfil de recebedor. No lado do pagador, você resolve um QR dinâmico lido para a cobrança dele. O trilho retorna a cobrança apenas depois que o certificado do site do recebedor e a assinatura do payload passam nas verificações dele.

​
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.
A solicitação de cancelamento (camt.055) também não recebe counterpartyIspb nem requestedBy. O trilho lê os dois participantes e o lado que solicita a partir do pain.013 do agendamento. O trilho aceita os motivos CCLD e FAIL apenas quando sua instituição é o participante do pagador no agendamento. Na resposta a um camt.055 recebido (camt.029), participantIspb nomeia o participante a quem o camt.055 se dirigiu. Qualquer outro valor recebe 422. Quando o trilho envia um camt.055 e nenhum camt.029 o responde em até 12 horas, o cancelamento tem efeito: o trilho cancela o agendamento e publica spi_schedule.resolved. Se o BACEN pode não ter recebido o camt.055, ou se a cobrança já pode ter sido liquidada, o trilho move a operação para REQUIRES_OPERATOR_ACTION em vez disso. O trilho pode rejeitar uma solicitação de cancelamento recebida (camt.055) com um camt.029. Se o BACEN recusar esse camt.029 e não aceitar nenhum reenvio em até 12 horas após a chegada do camt.055, o trilho cancela o agendamento. Se a cobrança já puder ter sido liquidada, o trilho mantém o agendamento e move sua operação para REQUIRES_OPERATOR_ACTION.

​
Disputas MED

Você trata os casos de fraude e erro do MED (Mecanismo Especial de Devolução) no DICT e reporta as liquidações internas no SPI:
  • Registre solicitações de reembolso do DICT, marcadores de fraude e solicitações de recuperação de fundos. Uma recuperação de fundos é rastreada por seu grafo de ciclo de vida.
  • Leia, reconheça, cancele, encerre e atualize relatos de infração do DICT.
  • 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) para o saldo (camt.053), o extrato (camt.052) ou o detalhe de lançamento (camt.054). O relatório sempre cobre a Conta PI do seu participante direto. Você lê o saldo e o extrato de volta pela API. Relatórios síncronos completam a superfície de relatórios: uma volumetria apenas de contagem, uma contagem de pagamentos rejeitados com uma lista paginada, e listagens de saldo e de extrato. Cada janela de relatório cobre no máximo 92 dias. Você também registra os responsáveis da Conta PI do seu participante direto (reda.022) e lê de volta o último registro conhecido deles.

​
Arquivo regulatório

O Lerian SPI arquiva cada envelope ICOM que envia ao BACEN ou recebe dele, e cada requisição e resposta do DICT, com seus headers. Ele também arquiva os certificados que os assinam ou verificam. Cada item traz seu prazo de retenção do Manual de Segurança do SFN, capítulo 7. Se o trilho não consegue arquivar uma mensagem de saída, ele não a envia. GET /api/v1/spi/regulatory-archive/{itemId} retorna um item arquivado byte a byte, para que você possa verificar a assinatura dele de novo. A rota aceita apenas um usuário, não uma aplicação, com o recurso br-spi-regulatory-archive do Access Manager e a ação read. O trilho registra quem leu qual item e quando antes de retornar o conteúdo. Uma leitura que o trilho não consegue registrar não retorna nada. Você configura o armazenamento do arquivo com as variáveis de ambiente REGULATORY_ARCHIVE_*. Apenas um ambiente de desenvolvimento pode iniciar sem ele.