Skip to main content
O SPI gerencia transferências Pix, devoluções, resultados assíncronos e o Block Balancer do MED 2.0. Ele chama o Midaz para a ação contábil correspondente à operação.
As rotas de callback de cash-in e cash-out são exclusivas do adaptador. Uma aplicação cliente não deve enviar um callback nem declarar um resultado de liquidação do provedor.

​
Enviar um cash-out em duas etapas

Um cash-out é intencionalmente dividido entre iniciação e processamento.
  1. Chame Iniciar transferência com um novo valor de X-Idempotency. O plugin valida a requisição e cria uma iniciação de transferência. Ele recusa um destino manual do tipo SLRY (conta-salário).
  2. Chame Processar transferência para essa iniciação. O plugin executa o débito necessário no Midaz e envia o trabalho ao adaptador de conectividade.
  3. Leia a transferência com Obter transferência. A aceitação do processamento não é um resultado final de pagamento.
  4. Deixe o adaptador de conectividade entregar o callback terminal. Leia novamente até a transferência chegar a um estado concluído, rejeitado ou outro estado terminal conforme o contrato da resposta.
Se o plugin não conseguir provar que não enviou o pagamento, ele mantém o débito e responde 201 com o status PROCESSING. Um 502 com PIX-0325 significa que o plugin não enviou o pagamento e tentou reverter o débito. Uma transferência ou devolução que fica em PROCESSING por 90 minutos ou mais pode ser resolvida com Desbloquear transferência ou Desbloquear devolução. O plugin consulta o SPI sobre o resultado e o aplica. Mantenha o mesmo valor de idempotência somente para repetir a mesma chamada. Um novo pagamento de negócio exige um novo valor.

​
Receber um cash-in pelo limite do adaptador

O adaptador recebe o evento do lado externo, chama os callbacks internos de aprovação e liquidação do plugin, e o plugin valida e credita o destino por meio do Midaz. Sua aplicação observa esse fluxo pelas leituras públicas da transferência: use direction=in para listar as transferências que uma conta recebeu. Ela não chama os callbacks de aprovação ou liquidação. Um cash-in que não pode ser aprovado ou liquidado não é uma decisão de retry do lado do cliente. Inspecione o estado público da operação antes de tomar outra ação.

​
Verificação de fraude no Pix recebido

A sua instituição pode verificar um Pix recebido com o próprio sistema de fraude antes que o Pix Lerian o aprove. A verificação vem desligada por padrão. Cada tenant liga a verificação na configuração de tempo de execução do SPI. O Pix Lerian verifica primeiro a conta de destino. Um Pix que a verificação da conta recusa não chega ao seu endpoint. As liquidações do Pix Automático e as devoluções recebidas não são verificadas.

​
A requisição

O Pix Lerian envia uma requisição POST com um corpo JSON:
  • contractVersion: 1.0.
  • eventType: PIX_CASHIN.
  • approvalId: um UUID. Toda requisição sobre o mesmo Pix traz o mesmo valor.
  • requestedAt e respondBy: timestamps em UTC. respondBy é o momento até o qual o Pix Lerian espera a sua resposta.
  • cashin: o valor, o endToEndId, o pagador (debitParty), o recebedor (creditParty) e a conta que recebe o crédito (account).
Cada requisição traz estes headers:
  • X-Webhook-Timestamp: o horário Unix, em segundos, da assinatura.
  • X-Webhook-Signature: v1,sha256=<hex>, em que <hex> é o HMAC-SHA256 em minúsculas de v1:<timestamp>.<raw body> com antifraud_hook_secret como chave.
  • Idempotency-Key: o approvalId.
  • O seu header, quando você configura um.
Verifique a assinatura sobre o corpo bruto antes de decidir.

​
A resposta

Responda com um status 2xx e um objeto JSON com um campo decision:
  • APPROVE ou ALLOW: o Pix Lerian aprova o Pix.
  • REJECT, DENY ou REVIEW: o Pix Lerian recusa o Pix com o código de motivo FRAD, e nada é creditado.
O Pix Lerian pode perguntar de novo sobre o mesmo Pix com o mesmo Idempotency-Key. Dê a mesma decisão todas as vezes.

​
Quando o seu endpoint não responde

O Pix Lerian aplica a decisão de contingência quando não recebe uma decisão: em um timeout, um erro de conexão, um status fora de 2xx, um redirecionamento, uma resposta que ele não consegue ler ou uma configuração incompleta. Depois de falhas repetidas, o Pix Lerian para de chamar o seu endpoint por um curto período e aplica a contingência. Uma recusa pela contingência sai com o código de motivo DS04.
A contingência padrão é APPROVE. Com esse padrão, enquanto o seu endpoint não responde, o Pix Lerian aprova Pix recebidos sem a sua verificação, até antifraud_hook_fallback_max_approve_amount quando você configura esse valor.

​
Criar e observar uma devolução

Use Criar devolução para uma transferência elegível e leia-a por meio de Obter devolução. reasonCode aceita somente MD06, SL02, FR01 e BE08. Uma devolução que o trilho recusa responde 422 (PIX-0013). Uma devolução segue seu próprio ciclo de vida assíncrono. Não a marque como concluída até que o plugin registre o resultado terminal do provedor e o efeito correspondente no Midaz. Uma nova tentativa com o mesmo valor de X-Idempotency em até uma hora após a primeira resposta 2xx retorna a devolução existente com 200. Depois de um 5xx ou de um 409 (PIX-0406), a primeira tentativa ainda pode estar PROCESSING com o seu débito. Chame Listar devoluções com transferId antes de tentar de novo.

​
Usar o Block Balancer do MED 2.0

O Block Balancer retém fundos de uma transação contestada antes de uma decisão de devolução. Esse é um fluxo operacional controlado, não um atalho para transferências comuns.
  1. Crie uma retenção para a transação contestada. O plugin coloca uma retenção pendente do Midaz do saldo disponível na conta de bloqueio configurada. Um replay do mesmo request_ref retorna a retenção existente.
  2. Se o caso terminar antes da liquidação, libere uma retenção PENDING. Você não pode liberar uma retenção que já está em liquidação.
  3. Inicie a liquidação da Fase 1 para uma retenção ou um grupo elegível. A retenção se torna SETTLING. O ramo retorna a retenção pendente e envia uma devolução, ou confirma a retenção, trata qualquer excedente e envia o pagamento necessário.
  4. Conclua a Fase 2 somente a partir do resultado observado da operação vinculada. Um sucesso torna a retenção SETTLED. Uma falha a compensa para PENDING.
  5. Use o fechamento manual, a devolução de excedente e as funções de auditoria somente pelos controles operacionais autorizados. Elas não são endpoints normais da aplicação.
O Block Balancer impõe um teto sobre suas próprias liquidações e as devoluções regulares de saída para a mesma transação original. Não tente contornar essa proteção calculando no cliente. Para o fluxo de infração e recuperação de fundos no DICT, consulte DICT.