> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Usar o SPI com o Pix Lerian > Execute os fluxos de cash-out, callback de cash-in, devolução e retenção de saldo do MED 2.0 do Pix Lerian com o Midaz e um adaptador de conectividade. 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. > [!NOTE] > > 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/initiate-transfer.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/process-transfer.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-transfer.md). 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/unblock-transfer.md) ou [Desbloquear devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/unblock-refund.md). 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. | Configuração | Padrão | O que faz | | - | - | - | | `antifraud_hook_enabled` | Desligada | `true` liga a verificação. | | `antifraud_hook_url` | Nenhum | O endereço do seu endpoint de decisão. Ele deve usar `https` e resolver para um endereço público, a menos que `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK` seja `true`. | | `antifraud_hook_secret` | Nenhum | A chave que assina cada requisição. Pelo menos 16 caracteres. | | `antifraud_hook_timeout_ms` | `500` | Quanto tempo o Pix Lerian espera por uma decisão, de `100` a `5000` milissegundos. | | `antifraud_hook_fallback_decision` | `APPROVE` | `APPROVE` ou `REJECT`: a decisão que o Pix Lerian aplica quando não recebe uma decisão do seu endpoint. | | `antifraud_hook_fallback_max_approve_amount` | Nenhum | Com a contingência `APPROVE`, o Pix Lerian aprova um valor até este limite e recusa um valor maior. | | `antifraud_hook_auth_header_name`, `antifraud_hook_auth_header_value` | Nenhum | Um header que o Pix Lerian adiciona a cada requisição, por exemplo para um gateway de API. Configure os dois ou nenhum. | 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=`, em que `` é o HMAC-SHA256 em minúsculas de `v1:.` 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`. > [!WARNING] > > 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/create-refund.md) para uma transferência elegível e leia-a por meio de [Obter devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-refund.md). `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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/list-refunds.md) 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](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-dict.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.