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

# Detecção

***

O plugin marca uma transferência como intra-PSP quando o ISPB de destino corresponde ao `PIX_ISPB` que você configurou:

| Tipo de iniciação | Origem do ISPB de destino                            |
| ----------------- | ---------------------------------------------------- |
| `KEY` / `QR_CODE` | Resposta da consulta ao DICT (`account.participant`) |
| `MANUAL`          | `destination.ispb` 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.

# 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 os mesmos pipelines `CashinApprovalCommand` e `CashinSettlementCommand` de um cash-in externo. Esses pipelines 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 (existing)
  → Picks up the record and delivers it (HTTP + HMAC)
    to POST /v1/payment/intra-psp/transfers/webhooks

Intra-PSP endpoint (orchestrates the full lifecycle)
  → CashinApprovalCommand → ACCEPTED / DENIED
  → ACCEPTED  → CashinSettlementCommand → Midaz credit → Cashout COMPLETED
  → DENIED / settlement fails → revert Midaz debit → Cashout FAILED
  → Report to BTG TRCK002 (async, non-blocking)
  → Outbound webhooks: cashout.completed/failed + cashin.completed
```

<Note>
  O cash-out responde com `PROCESSING`, como um cash-out externo que espera pelo BTG. O plugin entrega o status final (`COMPLETED` ou `FAILED`) 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.
</Note>

# 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 `TransactionReport` 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 persiste um webhook de saída `REFUND` (fluxo DICT) para avisar o solicitante, e a liquidação do cash-in intra-PSP enfileira `cashin.completed` 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](/pt/interfaces/pix-btg/indirect-pix-refund-operations).
</Warning>

# Motivos de falha

***

O plugin entrega uma falha de validação de cash-in de forma assíncrona pelo webhook `cashout.failed`. Em uma falha intra-PSP, o webhook carrega o motivo `INTRA_PSP_REJECTED` e uma mensagem sanitizada. Mensagens comuns:

| Mensagem                                     | Significado                                          |
| -------------------------------------------- | ---------------------------------------------------- |
| `pix key not found`                          | A chave Pix não existe no DICT.                      |
| `pix key is not active`                      | A chave Pix existe, mas está inativa.                |
| `pix key does not match account`             | A chave Pix não pertence à conta de destino.         |
| `account cannot receive payment`             | A conta de destino não pode receber o pagamento.     |
| `collection validation rejected the payment` | A cobrança do QR code dinâmico rejeitou o pagamento. |
| `duplicate transaction`                      | Já existe um cash-in com o mesmo ID end-to-end.      |

# Próximos passos

***

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