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 antes de un estado final. La tabla de la sección Desbloquear operaciones atascadas lista los estados que acepta cada desbloqueo.

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

Reenviar una devolución

Una solicitud de devolución lleva X-Idempotency, X-Return-End-To-End o ambos. Una solicitud con ninguno de los dos se rechaza con 400 PIX-0001, y no se mueve dinero. Cuando la primera devolución no está FAILED, un reenvío con la misma ancla y la misma solicitud la devuelve y no crea una segunda, salvo en el caso que describe PIX-3005 más abajo.
  • La misma clave X-Idempotency para la misma cuenta y la misma transferencia se rechaza con 422 PIX-3004 cuando el cuerpo de la solicitud difiere del primero, o cuando la primera devolución falló en su propia llamada de creación.
  • Un X-Return-End-To-End que pertenece a una devolución con una solicitud distinta, o a una devolución FAILED, se rechaza con 409 PIX-0423.
  • Mientras una solicitud con la misma clave X-Idempotency sigue en proceso, un reenvío se rechaza con 409 PIX-3002. Reintenta después del intervalo de Retry-After.
  • Cuando la primera solicitud bajo una clave X-Idempotency se ejecutó, pero su resultado no se registró, un reenvío se rechaza con 422 PIX-3005. Concilia la primera devolución. No la reenvíes ni reintentes con una clave nueva.
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 R$ 50,000.00: R$ 49,000.00 a la cuenta del cliente y R$ 1,000.00 a una cuenta de comisiones. Tras el fraude, la devolución debe ser de R$ 1,000.82. Solo quedan R$ 0.82 en la cuenta del cliente. El array operations debita R$ 0.82 de la cuenta del cliente y R$ 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 o fallar con un error de servidor antes de que BTG la confirme. La devolución queda entonces en PENDING, 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. Cuando el plugin liquida un cash-in o un cash-in de devolución más de 300 segundos después de su creación, primero busca un crédito que Midaz ya tenga para él. Si encuentra uno, completa el cash-in sobre ese crédito y no acredita de nuevo. Si la consulta falla, o el crédito encontrado fue revertido, el unblock falla y no acredita nada.

Operaciones paradas en CREATED

Un cashout o una devolución de cashout queda en CREATED cuando el plugin no puede conocer el resultado del débito en Midaz. El plugin no envía ningún Pix para él. El desbloqueo rechaza un cashout o una devolución inter-PSP en CREATED con 422 PIX-0470. Abre un ticket de soporte con Lerian e indica el id de la transferencia o de la devolución.

Rechazos

El desbloqueo también responde 422 PIX-0470 en estos casos:
  • Un cashout o una devolución inter-PSP está en PENDING y cambió hace menos de 150 segundos. La llamada de creación todavía puede estar enviándolo a BTG. Reintenta después de ese plazo.
  • El cashout o la devolución ya es final. Si una llamada anterior respondió 500 después de que el cashout quedó final, repite la llamada.

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.

Operaciones intra-PSP

El desbloqueo liquida un cashout o una devolución intra-PSP solo en Midaz y no consulta a BTG. Consulta Transferencias intra-PSP.

Próximos pasos