Transferencias intra-PSP

Cómo el Plugin Pix Indirecto vía BTG liquida las transferencias intra-PSP (P2P) y las devoluciones en una sola transacción de Midaz, sin liquidación en BTG, e informa a BACEN mediante TRCK002.

Una transferencia intra-PSP (también llamada P2P) es una transferencia Pix entre un pagador y un receptor 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. Aun así, el plugin informa la transferencia a BACEN por cumplimiento regulatorio.

El plugin admite transferencias y devoluciones intra-PSP. Las liquida internamente e informa cada una a BACEN mediante TRCK002.

Detección

---

El plugin marca una transferencia como intra-PSP cuando el ISPB de destino coincide con el ISPB del pagador, el bankingDetails.bankId de la cuenta alias del pagador en el CRM:

Tipo de iniciación	Origen del ISPB de destino
KEY / QR_CODE	Respuesta de la consulta a DICT (account.participant)
MANUAL	destination.account.participant 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. Un cobro de Pix Saque o Pix Troco no puede liquidarse internamente: el plugin lo rechaza con PIX-0497 (422).

Un Pix a la cuenta del propio pagador se rechaza cuando lo procesas, con PIX-0460 (422). El destino es la cuenta del propio pagador cuando el documento del titular, la agencia y el número de cuenta coinciden. El plugin no crea el cashout y no llama a Midaz.

Modelo de procesamiento

---

Una transferencia intra-PSP se liquida en una sola transacción de Midaz. El plugin verifica primero al receptor. Una transacción de Midaz debita entonces al pagador y acredita al receptor y a las cuentas de tarifa. La transacción no tiene tramo @external. El plugin liquida la transferencia dentro de la llamada de procesamiento y no espera webhooks de BTG.

Si el receptor es denegado, el plugin no debita nada. El cashout pasa a PROCESSING y luego a REJECTED.

Flujo

---

Process Cashout (intra-PSP detected)
  → Payee approval → ACCEPTED / DENIED (no debit at this step)
  → DENIED   → Cashout PROCESSING → REJECTED
  → ACCEPTED → one Midaz transaction: payer → payee and fee accounts
  → Cashout status → PROCESSING
  → Cash-in recorded → Cashout COMPLETED
  → Report to BTG TRCK002 (async, non-blocking)
  → Outbound webhooks: TRANSFER/CASHOUT + TRANSFER/CASHIN
  → Return PROCESSING to client

El cashout responde con PROCESSING, igual que un cashout externo que espera a BTG. El plugin entrega el estado final (COMPLETED o REJECTED) mediante un webhook saliente.

Informes regulatorios TRCK002

---

El plugin informa cada transacción intra-PSP exitosa a BACEN mediante el endpoint TRCK002 de BTG.

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

Devoluciones intra-PSP

---

El plugin también procesa una devolución internamente 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.
• Verifica primero al pagador original. Si ese lado es denegado, el plugin no debita nada, y la devolución pasa a PROCESSING y luego a REJECTED. En caso contrario, una transacción de Midaz mueve la devolución del solicitante al pagador original. Lleva intraPsp: true en sus metadatos.
• El plugin informa la devolución a TRCK002 con una returnIdentification.
• El plugin envía un webhook REFUND / CASHOUT para el solicitante de la devolución y un webhook REFUND / CASHIN para el remitente original.

Operaciones intra-PSP atascadas

---

BTG nunca retiene un cashout ni una devolución intra-PSP, así que el desbloqueo los liquida solo en Midaz. El desbloqueo lee la transacción de la operación en Midaz:

• Si Midaz tiene la transacción, el desbloqueo registra ambos lados y completa la operación.
• Si Midaz muestra que la transacción fue revertida, el desbloqueo mueve la operación a FAILED.
• Si Midaz no tiene transacción, el desbloqueo responde 422 PIX-0470. Una transacción ausente no prueba que el débito nunca entró. Para una operación parada en CREATED, abre una solicitud de soporte con Lerian e indica el id de la transferencia o de la devolución.
• Un cashout o una devolución cuyo receptor o pagador fue denegado no tiene transacción en Midaz: el desbloqueo lo mueve a REJECTED.

Un cashout en CREATED se acepta 65 minutos después de su creación, y uno en PENDING 65 minutos después de su último cambio. Una devolución se acepta 65 minutos después de su último cambio, mientras no es final. Consulta Operaciones de devolución.

Próximos pasos

---

• Webhooks: Envelope del evento, reintentos y enrutamiento
• Operaciones de devolución: Devoluciones distribuidas y desbloqueo
• Configurar la integración: Configuración del ISPB y del worker
• Referencia de API: Documentación completa de la API