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

# Transferencias intra-PSP

> Cómo el Plugin Pix Indirecto (BTG) procesa transferencias y reembolsos intra-PSP (P2P) internamente, sin liquidación de BTG, reportando vía TRCK002.

Una transferencia intra-PSP (también llamada P2P) es una transferencia Pix entre un pagador y un beneficiario en el **mismo participante**. El ISPB de origen y el de destino son idénticos. El dinero nunca sale de la institución, por lo que el plugin liquida la transferencia internamente y no la enruta a BTG. El plugin aún reporta la transferencia a BACEN por cumplimiento regulatorio.

<Note>
  El plugin soporta transferencias y reembolsos intra-PSP. Los liquida internamente y reporta cada uno a BACEN a través de TRCK002.
</Note>

# Detección

***

El plugin marca una transferencia como intra-PSP cuando el ISPB de destino coincide con tu `PIX_ISPB` configurado:

| Tipo de iniciación | Fuente del ISPB de destino                         |
| ------------------ | -------------------------------------------------- |
| `KEY` / `QR_CODE`  | Respuesta de consulta DICT (`account.participant`) |
| `MANUAL`           | `destination.ispb` en el payload de la solicitud   |

La detección es interna. La respuesta de iniciación y el estado del cashout coinciden con los de una transferencia externa. El plugin enruta una transferencia intra-PSP por la ruta de liquidación interna en lugar de BTG.

# Modelo de procesamiento

***

Una transferencia intra-PSP usa el mismo enrutamiento de Midaz que una transferencia externa, a través de la cuenta de tránsito `@external`. El comportamiento del libro mayor es idéntico. El plugin liquida la transferencia de forma síncrona y no espera los webhooks de BTG.

El plugin crea dos transacciones de Midaz por transferencia:

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

El cash-in interno reutiliza los mismos pipelines `CashinApprovalCommand` y `CashinSettlementCommand` que un cash-in externo. Estos pipelines ejecutan la validación de alias de CRM, las verificaciones de saldo, la titularidad de la clave PIX, la finalización del cobro y el cálculo de tarifas.

## Flujo

***

```
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>
  El cashout responde con `PROCESSING`, como un cashout externo que espera a BTG. El plugin entrega el estado final (`COMPLETED` o `FAILED`) de forma asíncrona a través de un webhook saliente. El endpoint intra-PSP es idempotente, por lo que los reintentos del worker nunca duplican transacciones.
</Note>

# Reporte regulatorio TRCK002

***

El plugin reporta cada transacción intra-PSP exitosa a BACEN a través del endpoint **TRCK002** de BTG.

* El reporte TRCK002 es **no bloqueante**. Una falla de reporte nunca revierte la transacción de Midaz ni la finalización de la transferencia. El plugin reintenta un reporte fallido.
* El plugin crea un `TransactionReport` por cada transacción. Después de que BTG acepta el envío, el estado del reporte pasa a `PROCESSING` y lleva un `pactualId`.
* BTG envía las actualizaciones de estado del reporte a través de un webhook **CAMT025**, de tipo `PIX_INTERNAL_TRANSACTIONS_REPORT`. El webhook mueve el reporte a `CONFIRMED` (terminal) o `ERROR` (recuperable).
* También puedes consultar un reporte por end-to-end ID o por identificación de devolución cuando un webhook no llega.

# Reembolsos intra-PSP

***

El plugin también procesa un reembolso de forma interna cuando el cash-in original fue intra-PSP:

* El plugin detecta intra-PSP a partir de la transferencia original, cuando su ISPB de origen y de destino coinciden.
* Debita al solicitante del reembolso (`requester → @external`). Luego entrega el cash-in del reembolso al remitente original a través del mismo patrón de cola y endpoint.
* El plugin reporta el reembolso a TRCK002 con un `returnIdentification`.
* El plugin persiste un webhook saliente `REFUND` (flujo DICT) para notificar al solicitante, y la liquidación de cash-in intra-PSP encola `cashin.completed` para el remitente original.

<Warning>
  No llames a unblock para una transferencia intra-PSP. El flujo de desbloqueo consulta a BTG por el estado de la transferencia. BTG nunca procesa una transacción interna, por lo que la consulta no aplica. Consulta [Operaciones de reembolso](/es/rails/pix/btg/indirect-pix-refund-operations).
</Warning>

# Motivos de falla

***

El plugin entrega una falla de validación de cash-in de forma asíncrona a través del webhook `cashout.failed`. Para una falla intra-PSP, el webhook lleva el motivo `INTRA_PSP_REJECTED` y un mensaje saneado. Mensajes comunes:

| Mensaje                                      | Significado                                       |
| -------------------------------------------- | ------------------------------------------------- |
| `pix key not found`                          | La clave PIX no existe en DICT.                   |
| `pix key is not active`                      | La clave PIX existe pero está inactiva.           |
| `pix key does not match account`             | La clave PIX no pertenece a la cuenta de destino. |
| `account cannot receive payment`             | La cuenta de destino no puede recibir el pago.    |
| `collection validation rejected the payment` | El cobro por QR code dinámico rechazó el pago.    |
| `duplicate transaction`                      | Ya existe un cash-in con el mismo end-to-end ID.  |

# Próximos pasos

***

* [Webhooks](/es/rails/pix/btg/indirect-pix-webhooks) — Envoltorio de eventos, reintentos y enrutamiento
* [Operaciones de reembolso](/es/rails/pix/btg/indirect-pix-refund-operations) — Reembolsos distribuidos y desbloqueo
* [Configurar la integración](/es/rails/pix/btg/indirect-pix-integration) — Configuración de ISPB y del worker
* [Referencia de API](/es/reference/midaz/plugins/indirect-pix/create-entry) — Documentación completa de la API