> ## 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 (BTG) processa transferências intra-PSP (P2P) e devoluções internamente — sem liquidação no BTG — ainda reportando ao BACEN via TRCK002.

Transferências intra-PSP (também chamadas de P2P) são transferências Pix em que o pagador e o recebedor pertencem ao **mesmo participante** — o ISPB de origem e o de destino são idênticos. Como o dinheiro nunca sai da instituição, essas transferências são liquidadas internamente em vez de serem roteadas ao BTG para liquidação. Elas ainda devem ser reportadas ao BACEN para conformidade regulatória.

<Note>
  Versões anteriores do plugin rejeitavam transferências intra-PSP com o erro `PIX-0406: Intra PSP Not Supported`. Esse erro foi removido — transferências e devoluções intra-PSP agora têm suporte completo.
</Note>

# Detecção

***

O plugin marca uma transferência como intra-PSP quando o ISPB de destino é igual ao seu `PIX_ISPB` configurado:

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

Quando detectada, a resposta de iniciação inclui `isIntraPSP: true`:

```json theme={null}
POST /v1/transfers/cashout/initiate
→ 201 Created
{
  "id": "uuid",
  "status": "PENDING",
  "isIntraPSP": true,
  "expiresAt": "2026-02-25T12:05:00Z"
}
```

A flag `isIntraPSP` é propagada para as entidades `Transfer`, `Cashout`, `Cashin` e `Refund` para consulta e conciliação.

# Modelo de processamento

***

Transferências intra-PSP seguem o **mesmo roteamento Midaz das transferências externas** (por meio da conta de trânsito `@external`), de modo que o comportamento do ledger é idêntico. A única diferença é que a liquidação ocorre de forma síncrona dentro do plugin, em vez de via webhooks do BTG.

Duas transações Midaz são criadas por transferência:

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

O cashin interno reutiliza exatamente os mesmos pipelines `CashinApprovalCommand` e `CashinSettlementCommand` dos cash-ins externos, incluindo 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

***

```
Process Cashout (isIntraPSP = true)
  → 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/webhooks/intra-psp/events

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 cashout responde com `PROCESSING`, exatamente como um cashout externo aguardando o BTG. O status final (`COMPLETED`/`FAILED`) é entregue de forma assíncrona via webhook de saída. O endpoint intra-PSP é totalmente idempotente, então as retentativas do worker nunca duplicam transações.
</Note>

# Reporte regulatório TRCK002

***

Toda transação intra-PSP bem-sucedida é reportada ao BACEN por meio do endpoint de abstração **TRCK002** do BTG, dentro do SLA regulatório de **P99 ≤ 300 segundos**.

* O reporte TRCK002 é **não bloqueante** — uma falha de reporte nunca reverte a transação Midaz nem a conclusão da transferência. Reportes que falham são reprocessados com backoff exponencial.
* O BTG retorna uma entidade `PixInternalTransactionsReport` com um `pactualId` e um status inicial `PROCESSING`.
* Atualizações de status do reporte chegam via webhook **CAMT025** (`PixInternalTransactionsReport`) no endpoint de eventos do BTG, transicionando o reporte para `CONFIRMED` ou `ERROR`.
* Como fallback quando webhooks são perdidos, o status do reporte pode ser consultado por identificador end-to-end ou identificação de retorno.

# Devoluções intra-PSP

***

Uma devolução para uma transferência cujo cash-in original foi intra-PSP também é processada internamente:

* O plugin detecta o caso intra-PSP quando o cashin original tem `isIntraPSP = true`.
* Ele debita o solicitante da devolução (`requester → @external`), depois orquestra o cash-in da devolução ao remetente original por meio do mesmo padrão de fila + endpoint.
* A devolução é reportada ao TRCK002 com um `returnIdentification`.
* Webhooks de saída: `refund.completed`/`refund.failed` para o solicitante e `cashin.completed` para o remetente original.

<Warning>
  O desbloqueio não tem suporte para transferências intra-PSP. O fluxo de desbloqueio consulta o BTG pelo status, o que não se aplica a transações internas, então chamá-lo retorna o erro `PIX-0418`. Consulte [Operações de devolução](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations).
</Warning>

# Motivos de falha

***

Falhas de validação do cash-in são entregues de forma assíncrona via o webhook `cashout.failed`. Motivos comuns de falha intra-PSP:

| Código                         | Descrição                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `RECIPIENT_ACCOUNT_INVALID`    | Validação de alias do CRM falhou (conta não encontrada, encerrada, bloqueada) |
| `RECIPIENT_CANNOT_RECEIVE`     | Validação de saldo no ledger falhou                                           |
| `PIX_KEY_OWNERSHIP_INVALID`    | A chave PIX não pertence à conta de destino                                   |
| `COLLECTION_INVALID`           | Validação da cobrança de QR code dinâmico falhou                              |
| `INTERNAL_CREDIT_FAILED`       | Transação de crédito no ledger falhou                                         |
| `INTERNAL_DEBIT_REVERT_FAILED` | Crítico — reversão do débito falhou; requer conciliação manual                |

# Próximos passos

***

* [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Envelope de eventos, retentativas e roteamento
* [Operações de devolução](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Devoluções distribuídas e desbloqueio
* [Configurando a integração](/pt/midaz/plugins/pix/indirect/indirect-pix-integration) — Configuração de ISPB e worker
* [Referência da API](/pt/reference/midaz/plugins/indirect-pix/create-entry) — Documentação completa da API