Operaciones de reembolso

Manejo avanzado de reembolsos en el Plugin Pix Indirecto (BTG): reembolsos parciales entre cuentas internas y desbloqueo de PROCESSING atascados.

El Plugin Pix Indirecto (BTG) procesa los reembolsos Pix (devoluções) a través del endpoint Reembolsar una transferencia Pix recibida. Dos capacidades extienden ese flujo para escenarios 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

---

Un Pix recibido puede dividirse internamente entre varias cuentas. Por ejemplo, el monto principal va a la cuenta del cliente y una tarifa va a una cuenta de tarifas. Un reembolso posterior por MED o fraude puede entonces debitar parte del monto de cada cuenta.

El flujo estándar de reembolso debita una sola cuenta. Para dividir el débito, envía un array opcional operations en el cuerpo de la solicitud. El array 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 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 posiciones 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 el reembolso 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 tarifas. Tras un fraude, el reembolso 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 tarifas. BTG recibe un único reembolso de R$ 1.000,82 sin consolidación manual del libro mayor.

​

Desbloqueo de operaciones atascadas

---

Una llamada de reversión a BTG puede expirar antes de que BTG la confirme. El reembolso o la transferencia queda entonces atascado en PROCESSING, y Midaz todavía retiene 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	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 o la 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. Esto evita 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

---

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 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 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 o ausente, o false, preserva el comportamiento estricto. Un 404 de BTG devuelve entonces un error y nunca revierte la retención. Opta por activarlo solo 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 resuelve el estado consultando a BTG. No aplica a las transferencias intra-PSP (internas), que no tienen transacción de BTG. 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