Saltar al contenido principal
El Plugin Pix Indirecto (BTG) procesa las devoluciones Pix (devoluções) mediante el endpoint Devolver una transferencia Pix recibida. Dos capacidades extienden ese flujo para escenarios de MED y de fraude:
  • Devoluciones parciales distribuidas: retorna una devolución desde varias cuentas internas en una sola operación
  • Desbloqueo: recupera una devolución o transferencia atascada en CREATED, PENDING o PROCESSING

​
Devoluciones parciales distribuidas

Un Pix recibido puede dividirse internamente entre varias cuentas. Por ejemplo, el monto principal va a la cuenta del cliente y una comisión va a una cuenta de comisiones. Una devolución posterior por MED o por fraude puede entonces debitar parte del monto de cada cuenta. El flujo de devolución estándar debita una cuenta. Para dividir el débito, envía un array operations opcional en el cuerpo de la solicitud. El array operations es la única señal. No hay un endpoint, una variable de entorno ni un feature flag nuevos.

​
Solicitud

  • Sin operations → se ejecuta sin cambios el flujo actual de una sola cuenta.
  • Con operations → el plugin debita cada accountAlias por su amount en Midaz, y BTG recibe un único pacs.004 por el valor total de la devolución.

​
Reglas de validación

El endpoint, el flujo de BTG (pacs.004 con el valor total), la idempotencia y la autenticación coinciden con los de la devolución estándar. Solo cambia la composición del débito interno en Midaz.

​
Ejemplo: división de comisión

El plugin dividió un cash-in de R50,000.00:R 50,000.00: R 49,000.00 a la cuenta del cliente y R1,000.00aunacuentadecomisiones.Traselfraude,ladevolucioˊndebeserdeR 1,000.00 a una cuenta de comisiones. Tras el fraude, la devolución debe ser de R 1,000.82. Solo quedan R0.82enlacuentadelcliente.Elarray‘operations‘debitaR 0.82 en la cuenta del cliente. El array `operations` debita R 0.82 de la cuenta del cliente y R1,000.00delacuentadecomisiones.BTGrecibeunauˊnicadevolucioˊndeR 1,000.00 de la cuenta de comisiones. BTG recibe una única devolución de R 1,000.82 sin consolidación manual en el ledger.

​
Desbloquear operaciones atascadas

Una llamada de reversión a BTG puede agotar el timeout antes de que BTG la confirme. La devolución o la transferencia queda entonces atascada en PROCESSING, y Midaz sigue reteniendo los fondos. Dos endpoints llevan una operación atascada a su estado terminal. Ambos requieren el header X-Account-Id de la cuenta dueña de la operación.

​
Cómo funciona el desbloqueo

El plugin vuelve a consultar el estado de la reversión o de la transferencia en BTG y:
  • Si BTG informa CONFIRMED o ERROR → despacha la liquidación correspondiente y lleva la operación a su estado terminal.
  • Si BTG sigue informando INITIATED/PROCESSING → devuelve HTTP 200 sin acción. Reintenta más tarde.
Una protección de consistencia aborta la operación si el entity, el returnIdentification o el originalEndToEndId de BTG difieren del registro local. Esto evita liquidar contra la transacción equivocada.
La respuesta incluye el refund actualizado, un message y el btgStatus.

​
Devoluciones de cashout en CREATED

Para una devolución de cashout en CREATED, el desbloqueo no consulta a BTG. Marca la devolución como FAILED y devuelve btgStatus: "NOT_CONTACTED". El plugin envía un webhook REFUND / CASHOUT con el código de error PRE_HOLD_STUCK.

​
Manejo de un 404 de BTG

BTG puede devolver 404 cuando ya no tiene la reversión o la transferencia. El resultado depende entonces del tipo de operación y del flag de activación explícita allowNotFoundUnblock en el cuerpo de la solicitud.
allowNotFoundUnblock tiene false como valor predeterminado. Un cuerpo vacío o ausente, o false, conserva el comportamiento estricto. Un 404 de BTG devuelve entonces un error y nunca revierte la retención. Actívalo solo cuando hayas confirmado que la operación debe liberarse.
La recuperación de 404 por activación explícita aplica solo a operaciones CASHOUT en PENDING/PROCESSING con un endToEndId no vacío. Los cash-ins y los estados terminales nunca entran en esta rama.

​
Limitación intra-PSP

No llames al desbloqueo de transferencias para una transferencia intra-PSP: no tiene una transacción en BTG que consultar. Consulta Transferencias intra-PSP.

​
Próximos pasos