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

POST /v1/transfers/{transfer_id}/refunds
{
  "amount": "1000.82",
  "description": "MED Cappta",
  "operations": [
    { "accountAlias": "alias-conta-cliente", "amount": "0.82" },
    { "accountAlias": "alias-conta-fee", "amount": "1000.00" }
  ]
}

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

Regla	Error
`sum(operations[].amount)` debe ser igual a `amount`	`400 PIX-0447` Operations Sum Mismatch
`accountAlias` no debe repetirse dentro de la solicitud	`400 PIX-0448` Duplicate Account Alias
cada `amount` debe ser mayor que `0`	`400 PIX-0004` Invalid Field Values
cada `amount` debe tener como máximo 2 decimales	`400 PIX-0004` Invalid Field Values
la solicitud debe contener como máximo 50 operaciones	`400 PIX-0013` Limit Exceeded
el cash-in original debe existir	`404 PIX-0425` Cashin Not Found

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: Cappta

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 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 vuelven a consultar a BTG y llevan la operación a su estado terminal.

Método	Endpoint	Desbloquea
`POST`	`/v1/refunds/{refund_id}/unblock`	Una devolución atascada en `PROCESSING`
`POST`	`/v1/transfers/{transfer_id}/unblock`	Una transferencia atascada en `PENDING`/`PROCESSING`

Ambos requieren el header X-Account-Id.

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.

POST /v1/refunds/{refund_id}/unblock
X-Account-Id: <account-id>

La respuesta incluye el refund actualizado, un message y el btgStatus.

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.

Operación	Predeterminado (estricto)	Con `allowNotFoundUnblock: true`
Transferencia (`/v1/transfers/{id}/unblock`)	Devuelve un error	Revierte la retención en Midaz (de mejor esfuerzo, idempotente), marca el cashout como `FAILED` con `BTG_NOT_FOUND`, emite un webhook saliente `CASHOUT` y devuelve `200` con `btgStatus: "NOT_FOUND"`
Devolución (`/v1/refunds/{id}/unblock`)	Devuelve `PIX-1012` (`ErrProviderRefundNotFound`)	Revierte la retención y lleva la devolución a su estado terminal

POST /v1/transfers/{transfer_id}/unblock
{
  "allowNotFoundUnblock": true
}

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

El flujo de desbloqueo de transferencias resuelve el estado consultando a BTG. No aplica a las transferencias intra-PSP (internas), que no tienen transacción en BTG. Consulta Transferencias intra-PSP.

Próximos pasos

Transferencias intra-PSP: Transferencias y devoluciones P2P internas
MED 2.0 — Recuperación de fondos: Recuperación de fraude entre cuentas
Webhooks: Manejo de eventos de devolución y de transferencia
Referencia de API: Documentación completa de la API

​Devoluciones parciales distribuidas

​Solicitud

​Reglas de validación

​Ejemplo: Cappta

​Desbloquear operaciones atascadas

​Cómo funciona el desbloqueo

​Manejo de un 404 de BTG

​Limitación intra-PSP

​Próximos pasos

Devoluciones parciales distribuidas

Solicitud

Reglas de validación

Ejemplo: Cappta

Desbloquear operaciones atascadas

Cómo funciona el desbloqueo

Manejo de un 404 de BTG

Limitación intra-PSP

Próximos pasos