- Devoluções parciais distribuídas — devolver um valor a partir de múltiplas contas internas em uma única operação
- Desbloqueio — recuperar uma devolução ou transferência presa em
PROCESSING
Devoluções parciais distribuídas
Um Pix recebido pode se dividir internamente entre várias contas. Por exemplo, o valor principal vai para a conta do cliente e uma tarifa vai para uma conta de tarifas. Uma devolução posterior por MED ou fraude pode então debitar parte do valor de cada conta. O fluxo de devolução padrão debita uma única conta. Para dividir o débito, envie um array opcional
operations no corpo da requisição. O array operations é o único sinal — não há novo endpoint, variável de ambiente ou feature flag.
Requisição
- Sem
operations→ o fluxo atual de conta única roda sem alterações. - Com
operations→ o plugin debita cadaaccountAliaspelo seuamountno Midaz, e o BTG recebe um único pacs.004 com o valor total da devolução.
Regras de validação
O endpoint, o fluxo do BTG (pacs.004 com o valor total), a idempotência e a autenticação são idênticos aos da devolução padrão. Apenas a composição do débito interno no Midaz muda.
Exemplo — Cappta
O plugin dividiu um cash-in de R 49.000,00 para a conta do cliente e R 1.000,82. Apenas R 0,82 da conta do cliente e R 1.000,82 sem consolidação manual no ledger.
Desbloqueio de operações presas
Uma chamada de reversão ao BTG pode expirar antes de o BTG confirmá-la. A devolução ou transferência fica então presa em
PROCESSING, e o Midaz ainda retém os fundos. Dois endpoints reconsultam o BTG e levam a operação ao seu estado terminal.
Ambos exigem o cabeçalho
X-Account-Id.
Como o desbloqueio funciona
O plugin reconsulta o status da reversão ou transferência no BTG e:
- Se o BTG reportar
CONFIRMEDouERROR→ dispara a liquidação correspondente e move a operação para seu estado terminal. - Se o BTG ainda reportar
INITIATED/PROCESSING→ retorna HTTP 200 sem ação — tente novamente mais tarde.
entity, returnIdentification ou originalEndToEndId do BTG divergirem do registro local. Isso evita a liquidação contra a transação errada.
refund atualizada, uma message e o btgStatus.
Tratamento de um 404 do BTG
O BTG pode retornar
404 quando não tem mais a reversão ou a transferência. O resultado depende então do tipo de operação e da flag opcional allowNotFoundUnblock no corpo da requisição.
A recuperação opcional de 404 se aplica apenas a operações
CASHOUT em PENDING/PROCESSING com um endToEndId não vazio. Cash-ins e status terminais nunca entram neste fluxo.Limitação intra-PSP
O fluxo de desbloqueio de transferência resolve o status consultando o BTG. Ele não se aplica a transferências intra-PSP (internas), que não têm transação no BTG. Consulte Transferências intra-PSP.
Próximos passos
- Transferências intra-PSP — Transferências e devoluções P2P internas
- MED 2.0 — Recuperação de Fundos — Recuperação de fraude entre contas
- Webhooks — Tratamento de eventos de devolução e transferência
- Referência da API — Documentação completa da API