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

# Transferências intra-PSP

> Como o Plugin Pix Indireto via BTG liquida internamente transferências e devoluções intra-PSP (P2P) sem a liquidação do BTG, reportando ao BACEN pelo TRCK002.

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 para o BTG. Mesmo assim, o plugin reporta a transferência ao BACEN para conformidade regulatória.

> [!NOTE]
>
> O plugin aceita transferências e devoluções intra-PSP. Ele as liquida internamente e reporta cada uma ao BACEN pelo TRCK002.

# Detecção

***

O plugin marca uma transferência como intra-PSP quando o ISPB de destino corresponde ao ISPB do pagador, o `bankingDetails.bankId` da conta alias do pagador no CRM:

| Tipo de iniciação | Origem do ISPB de destino |
| - | - |
| `KEY` / `QR_CODE` | Resposta da consulta ao DICT (`account.participant`) |
| `MANUAL` | `destination.account.participant` no payload da requisição |

A detecção é interna. A resposta da iniciação e o status do cash-out são iguais aos de uma transferência externa. O plugin roteia uma transferência intra-PSP pelo caminho de liquidação interno em vez do BTG. Uma cobrança de Pix Saque ou Pix Troco não pode liquidar internamente: o plugin a rejeita com `PIX-0497` (422).

# Modelo de processamento

***

Uma transferência intra-PSP usa o mesmo roteamento no Midaz que uma transferência externa, pela conta de trânsito `@external`. O comportamento no ledger é idêntico. O plugin liquida a transferência de forma síncrona e não espera pelos webhooks do BTG.

O plugin cria duas transações no Midaz por transferência:

1. **Cashout**: `source → @external` (`pending: false`)
2. **Cashin**: `@external → destination` (`pending: false`)

O cash-in interno reutiliza as mesmas etapas de aprovação e liquidação de um cash-in externo. Essas etapas fazem a validação de alias no CRM, checagens de saldo, posse da chave Pix, conclusão da cobrança e cálculo de tarifas.

## Fluxo

***

```
Process Cashout (intra-PSP detected)
  → Midaz debit: source → @external
  → Write inbound record to the webhook queue
  → Cashout status → PROCESSING (intermediary)
  → Return PROCESSING to client

Inbound worker
  → Picks up the record and delivers it (HTTP + HMAC)
    to POST /v1/payment/intra-psp/transfers/webhooks

Intra-PSP endpoint (orchestrates the full lifecycle)
  → Cash-in approval → ACCEPTED / DENIED
  → ACCEPTED  → Cash-in settlement → Midaz credit → Cashout COMPLETED
  → DENIED / settlement fails → revert Midaz debit → Cashout REJECTED
  → Report to BTG TRCK002 (async, non-blocking)
  → Outbound webhooks: TRANSFER/CASHOUT + TRANSFER/CASHIN
```

> [!NOTE]
>
> O cash-out responde com `PROCESSING`, como um cash-out externo que espera pelo BTG. O plugin entrega o status final (`COMPLETED` ou `REJECTED`) de forma assíncrona por um webhook de saída. O endpoint intra-PSP é idempotente, então novas tentativas do worker nunca duplicam transações.

# Reporte regulatório TRCK002

***

O plugin reporta ao BACEN cada transação intra-PSP bem-sucedida pelo endpoint **TRCK002** do BTG.

* O reporte TRCK002 é não bloqueante. Uma falha no reporte nunca reverte a transação no Midaz nem a conclusão da transferência. O plugin faz nova tentativa de um reporte que falhou.
* O plugin cria um relatório de transação para cada transação. Depois que o BTG aceita o envio, o status do relatório passa para `PROCESSING` e carrega um `pactualId`.
* O BTG envia atualizações de status do relatório por um webhook **CAMT025**, do tipo `PIX_INTERNAL_TRANSACTIONS_REPORT`. O webhook move o relatório para `CONFIRMED` (terminal) ou `ERROR` (recuperável).
* Você também pode consultar um relatório pelo ID end-to-end ou pela identificação de devolução 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`). Depois entrega o cash-in da devolução ao remetente original pelo mesmo padrão de fila e endpoint.
* O plugin reporta a devolução ao TRCK002 com uma `returnIdentification`.
* O plugin envia um webhook `REFUND` / `CASHOUT` para o solicitante da devolução e um webhook `REFUND` / `CASHIN` para o remetente original.

> [!WARNING]
>
> Não chame o desbloqueio para uma transferência intra-PSP. O fluxo de desbloqueio consulta o status da transferência no BTG. O BTG nunca processa uma transação interna, então a consulta não se aplica. Veja [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md).

# Próximos passos

***

* [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): Envelope de evento, novas tentativas e roteamento
* [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md): Devoluções distribuídas e desbloqueio
* [Configurar a integração](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-integration.md): Configuração de ISPB e do worker
* [Referência da API](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-entry.md): Documentação completa da API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.