Pular para o conteúdo principal
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. Um Pix recebido nunca paga tarifa. O Pix Lerian pede ao Midaz que dispense as tarifas em cada crédito de um Pix recebido e de uma devolução, e o Midaz só atende o pedido quando a configuração overrides.allowFeeSkip está ligada no ledger do Pix. Um pacote de tarifas de cash-out deve ser adicional: veja o erro PIX-0330. A Lerian ativa overrides.allowFeeSkip no ledger do Pix ao provisionar o serviç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 reverteu o débito. Um 500 (PIX-0000) significa que a reversão não está registrada: leia a transferência antes de agir. 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. Todo lançamento de Pix é feito contra @external/BRL por padrão. Quando a configuração settlement_account_alias do SPI nomeia uma conta comum, essa conta a substitui: um cash-out a credita e um Pix recebido a debita. Um cash-out imediato cujo crédito essa conta não pode receber responde 422 com PIX-0332. Altere a configuração somente quando nenhuma retenção de Pix Agendado estiver em vigor.

​
Creditar um Pix recebido que está estacionado

Quando o Midaz não confirma o crédito de um Pix recebido, ou de uma devolução, o Pix Lerian não o descarta. Ele estaciona o crédito e emite inbound_transfer.credit_parked ou refund.credit_parked (veja Eventos). O evento nomeia o motivo: Para LEDGER_OUTCOME_UNKNOWN e SETTLE_INTERRUPTED, chame de imediato. Para ACCOUNT_BLOCKED e LEDGER_REFUSED, corrija a causa primeiro e não chame automaticamente. Chame Creditar um Pix recebido cujo crédito no ledger está estacionado ou Creditar uma devolução de Pix recebida cujo crédito no ledger está estacionado para creditá-lo. A chamada nunca credita duas vezes: ela consulta o Midaz primeiro e responde 409 com PIX-0474 quando o Midaz não consegue confirmar o crédito; concilie à mão. O chamador precisa da permissão de enviar transferências, ou devoluções na rota de devoluçã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. Quando a resposta traz o motivo AG01, a recusa sai com AG01 no lugar, e a operação informa PIX-0458.
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 resposta original com o header X-Idempotency-Replayed: true. O valor continua ligado à devolução até ela ficar FAILED. Uma nova tentativa que muda a transferência, o valor, o reasonCode ou o motivo responde 412 (PIX-0031). 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. A referência da API chama cada retenção de bloqueio cautelar: veja Criar um bloqueio cautelar, Liquidar um bloqueio cautelar e Liberar um bloqueio cautelar ao titular da conta. As rotas de devolução do DICT liquidam as retenções de uma devolução MED: veja DICT.
  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. Feche uma retenção depois de uma devolução manual, devolva um excedente de liquidação ao titular da conta e leia os registros de auditoria com as rotas da referência da API em Bloqueios cautelares.
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.