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.

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

​

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

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.

​

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.

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.

​

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 — Envoltorio de eventos, reintentos y enrutamiento
• Operaciones de reembolso — Reembolsos distribuidos y desbloqueo
• Configurar la integración — Configuración de ISPB y del worker
• Referencia de API — Documentación completa de la API