> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/es/reference/midaz/plugins/indirect-pix/refund-a-received-pix-transfer). 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

***

```json theme={null}
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        |

<Note>
  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.
</Note>

## 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`](/es/reference/midaz/plugins/indirect-pix/unblock-a-pix-refund)       | Un reembolso atascado en `PROCESSING`                |
| `POST` | [`/v1/transfers/{transfer_id}/unblock`](/es/reference/midaz/plugins/indirect-pix/unblock-a-pix-transfer) | 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.

```json theme={null}
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`](/es/reference/midaz/plugins/indirect-pix/unblock-a-pix-transfer)) | 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`](/es/reference/midaz/plugins/indirect-pix/unblock-a-pix-refund))         | Devuelve `PIX-1012` (`ErrProviderRefundNotFound`) | Revierte la retención y lleva el reembolso a su estado terminal                                                                                                                                  |

```json theme={null}
POST /v1/transfers/{transfer_id}/unblock
{
  "allowNotFoundUnblock": true
}
```

<Warning>
  `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.
</Warning>

<Note>
  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.
</Note>

## 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](/es/rails/pix/btg/indirect-pix-intra-psp).

# Próximos pasos

***

* [Transferencias intra-PSP](/es/rails/pix/btg/indirect-pix-intra-psp) — Transferencias y reembolsos P2P internos
* [MED 2.0 — Recuperación de fondos](/es/rails/pix/btg/indirect-pix-med-2-funds-recovery) — Recuperación de fraude entre cuentas
* [Webhooks](/es/rails/pix/btg/indirect-pix-webhooks) — Manejo de eventos de reembolso y transferencia
* [Referencia de API](/es/reference/midaz/plugins/indirect-pix/create-entry) — Documentación completa de la API