El Plugin Pix Indirecto (BTG) procesa los reembolsos Pix (devoluções) a través del endpoint existente Reembolsar una transferencia Pix recibida. Dos capacidades extienden ese flujo para escenarios reales de MED y fraude:

Reembolsos parciales distribuidos — devuelve un reembolso desde múltiples cuentas internas en una sola operación
Desbloqueo — recupera un reembolso o una transferencia que está atascado en PROCESSING

Reembolsos parciales distribuidos

Cuando un Pix recibido se distribuye internamente entre varias cuentas — por ejemplo, el monto principal a la cuenta del cliente y una tarifa a una cuenta de tarifas — un reembolso posterior por MED/fraude puede necesitar debitarse parcialmente de cada una de esas cuentas. El flujo estándar de reembolso debita desde una sola cuenta. Para dividir el débito, envía un array opcional operations en el cuerpo de la solicitud. La presencia de operations es la única señal — no hay un nuevo endpoint, variable de entorno ni feature flag.

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 → el flujo actual de cuenta única se ejecuta sin cambios.
Con operations → el plugin debita cada accountAlias por su amount en Midaz, y BTG recibe un único pacs.004 por el valor total del reembolso.

Reglas de validación

Regla	Error
`sum(operations[].amount)` debe ser igual a `amount`	`400 OPERATIONS_SUM_MISMATCH`
`accountAlias` no debe repetirse dentro de la solicitud	`400 DUPLICATE_ACCOUNT_ALIAS`
cada `amount` debe ser mayor que `0`	`400`
cada `amount` debe tener como máximo 2 posiciones decimales	`400`
cada `accountAlias` debe haber participado en la transacción original	`422 ACCOUNT_ALIAS_NOT_IN_ORIGINAL_TRANSACTION`
la transacción original debe existir en Midaz	`422 ORIGINAL_TRANSACTION_NOT_FOUND`

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

Ejemplo — Cappta

Un cash-in de R

50.000,00 se dividió en R

49.000,00 a la cuenta del cliente y R

1.000,00 a una cuenta de tarifas. Tras un fraude, el reembolso requerido es de R

1.000,82, pero 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 tarifas, mientras BTG recibe un único reembolso de R

1.000,82 — sin necesidad de consolidación manual del libro mayor.

Desbloqueo de operaciones atascadas

Un reembolso o una transferencia cuya llamada de reversión a BTG expira antes de la confirmación puede quedar atascado en PROCESSING, con la retención todavía aplicada en Midaz. Dos endpoints dedicados vuelven a consultar a BTG y llevan la operación a su estado terminal correcto.

Método	Endpoint	Desbloquea
`POST`	`/v1/refunds/{refund_id}/unblock`	Un reembolso atascado en `PROCESSING`
`POST`	`/v1/transfers/{transfer_id}/unblock`	Una transferencia atascada en `PENDING`/`PROCESSING`

Ambos requieren el encabezado X-Account-Id.

Cómo funciona el desbloqueo

El plugin vuelve a consultar el estado de la reversión/transferencia en BTG y:

Si BTG reporta CONFIRMED o ERROR → despacha la liquidación correspondiente y lleva la operación a su estado terminal.
Si BTG todavía reporta 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, evitando la liquidación 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

Cuando BTG ya no tiene la reversión/transferencia (devuelve 404), el comportamiento depende del tipo de operación y del flag opcional allowNotFoundUnblock en el cuerpo de la solicitud:

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

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

allowNotFoundUnblock tiene por defecto false. Un cuerpo vacío/ausente o false preserva el comportamiento estricto (un 404 de BTG devuelve un error y nunca revierte la retención). Solo opta por activarlo cuando hayas confirmado que la operación debe liberarse.

La recuperación opcional ante un 404 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 consulta a BTG por el estado, lo cual no aplica a las transferencias intra-PSP (internas) — no hay transacción de BTG. Llamar al desbloqueo sobre una transferencia intra-PSP devuelve un error síncrono (PIX-0418). La lógica adecuada de desbloqueo intra-PSP es una mejora futura. Consulta Transferencias intra-PSP.

Próximos pasos

Transferencias intra-PSP — Transferencias y reembolsos P2P internos
MED 2.0 — Recuperación de fondos — Recuperación de fraude entre cuentas
Webhooks — Manejo de eventos de reembolso y transferencia
Referencia de API — Documentación completa de la API

​Reembolsos parciales distribuidos

​Solicitud

​Reglas de validación

​Ejemplo — Cappta

​Desbloqueo de operaciones atascadas

​Cómo funciona el desbloqueo

​Manejo de un 404 de BTG

​Limitación intra-PSP

​Próximos pasos

Reembolsos parciales distribuidos

Solicitud

Reglas de validación

Ejemplo — Cappta

Desbloqueo de operaciones atascadas

Cómo funciona el desbloqueo

Manejo de un 404 de BTG

Limitación intra-PSP

Próximos pasos