Skip to main content
Uma transferência intra-PSP (também chamada de P2P) é uma transferência Pix entre um pagador e um recebedor no mesmo participante. O ISPB de origem e o de destino são idênticos. O dinheiro nunca sai da instituição, então o plugin liquida a transferência internamente e não a roteia ao BTG. O plugin ainda reporta a transferência ao BACEN para conformidade regulatória.
O plugin oferece suporte a transferências e devoluções intra-PSP. Ele as liquida internamente e reporta cada uma ao BACEN por meio do TRCK002.

​
Detecção

O plugin marca uma transferência como intra-PSP quando o ISPB de destino corresponde ao seu PIX_ISPB configurado: A detecção é interna. A resposta de iniciação e o status do cashout correspondem aos de uma transferência externa. O plugin roteia uma transferência intra-PSP pela rota de liquidação interna em vez do BTG.

​
Modelo de processamento

Uma transferência intra-PSP usa o mesmo roteamento Midaz de uma transferência externa, por meio da conta de trânsito @external. O comportamento do ledger é idêntico. O plugin liquida a transferência de forma síncrona e não espera os webhooks do BTG. O plugin cria duas transações Midaz por transferência:
  1. Cashout — source → @external (pending: false)
  2. Cashin — @external → destination (pending: false)
O cash-in interno reutiliza os mesmos pipelines CashinApprovalCommand e CashinSettlementCommand de um cash-in externo. Esses pipelines executam validação de alias do CRM, verificações de saldo, propriedade da chave PIX, conclusão da cobrança e cálculo de tarifa.

​
Fluxo

O cashout responde com PROCESSING, como um cashout externo que aguarda o BTG. O plugin entrega o status final (COMPLETED ou FAILED) de forma assíncrona por meio de um webhook de saída. O endpoint intra-PSP é idempotente, então as retentativas do worker nunca duplicam transações.

​
Reporte regulatório TRCK002

O plugin reporta cada transação intra-PSP bem-sucedida ao BACEN por meio do endpoint TRCK002 do BTG.
  • O reporte TRCK002 é não bloqueante. Uma falha de reporte nunca reverte a transação Midaz nem a conclusão da transferência. O plugin reprocessa um reporte que falhou.
  • O plugin cria um TransactionReport para cada transação. Depois que o BTG aceita o envio, o status do reporte passa a PROCESSING e carrega um pactualId.
  • O BTG envia as atualizações de status do reporte por meio de um webhook CAMT025, do tipo PIX_INTERNAL_TRANSACTIONS_REPORT. O webhook move o reporte para CONFIRMED (terminal) ou ERROR (recuperável).
  • Você também pode consultar um reporte por end-to-end ID ou por identificação de retorno quando um webhook não chega.

​
Devoluções intra-PSP

O plugin também processa uma devolução internamente quando o cash-in original foi intra-PSP:
  • O plugin detecta intra-PSP a partir da transferência original, quando o ISPB de origem e o de destino coincidem.
  • Ele debita o solicitante da devolução (requester → @external). Em seguida, entrega o cash-in da devolução ao remetente original por meio do mesmo padrão de fila e endpoint.
  • O plugin reporta a devolução ao TRCK002 com um returnIdentification.
  • O plugin persiste um webhook de saída REFUND (fluxo DICT) para notificar o solicitante, e a liquidação de cash-in intra-PSP enfileira cashin.completed para o remetente original.
Não chame unblock para uma transferência intra-PSP. O fluxo de desbloqueio consulta o BTG pelo status da transferência. O BTG nunca processa uma transação interna, então a consulta não se aplica. Consulte Operações de devolução.

​
Motivos de falha

O plugin entrega uma falha de validação de cash-in de forma assíncrona por meio do webhook cashout.failed. Para uma falha intra-PSP, o webhook carrega o motivo INTRA_PSP_REJECTED e uma mensagem higienizada. Mensagens comuns:

​
Próximos passos