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. Nesta release, o provedor simulado fornecido é a forma compatível de exercê-las. 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.
  2. Chame Processar transferência para essa iniciação. O plugin executa o débito necessário no Midaz e envia o trabalho ao provedor simulado.
  3. Leia a transferência com Obter transferência. A aceitação do processamento não é um resultado final de pagamento.
  4. Deixe o provedor simulado entregar o callback terminal. Leia novamente até a transferência ser concluída, rejeitada ou chegar a outro estado terminal conforme o contrato da resposta.
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; 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 e as evidências do teste com mock antes de tomar outra ação.

​
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. 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.

​
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. Uma retenção que já está em liquidação não pode ser liberada.
  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.