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

# Operações de devolução

> Tratamento avançado de devoluções no Plugin Pix Indireto (BTG): devoluções parciais distribuídas entre múltiplas contas internas e desbloqueio de devoluções ou transferências presas em PROCESSING.

O Plugin Pix Indireto (BTG) processa devoluções Pix por meio do endpoint existente [Devolver uma transferência Pix recebida](/pt/reference/midaz/plugins/indirect-pix/refund-a-received-pix-transfer). Dois recursos estendem esse fluxo para cenários reais de MED e fraude:

* **Devoluções parciais distribuídas** — devolver um valor a partir de múltiplas contas internas em uma única operação
* **Desbloqueio** — recuperar uma devolução ou transferência presa em `PROCESSING`

# Devoluções parciais distribuídas

***

Quando um Pix recebido é distribuído internamente entre várias contas — por exemplo, o valor principal para a conta do cliente e uma tarifa para uma conta de tarifas — uma devolução posterior por MED/fraude pode precisar ser debitada parcialmente de cada uma dessas contas.

O fluxo de devolução padrão debita de uma única conta. Para dividir o débito, envie um array opcional `operations` no corpo da requisição. **A presença de `operations` é o único sinal** — não há novo endpoint, variável de ambiente ou feature flag.

## Requisição

***

```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" }
  ]
}
```

* Sem `operations` → o fluxo atual de conta única roda sem alterações.
* Com `operations` → o plugin debita cada `accountAlias` pelo seu `amount` no Midaz, e o BTG recebe um único pacs.004 com o valor **total** da devolução.

## Regras de validação

***

| Regra                                                          | Erro                                            |
| -------------------------------------------------------------- | ----------------------------------------------- |
| `sum(operations[].amount)` deve ser igual a `amount`           | `400 OPERATIONS_SUM_MISMATCH`                   |
| `accountAlias` não pode se repetir dentro da requisição        | `400 DUPLICATE_ACCOUNT_ALIAS`                   |
| cada `amount` deve ser maior que `0`                           | `400`                                           |
| cada `amount` deve ter no máximo 2 casas decimais              | `400`                                           |
| cada `accountAlias` deve ter participado da transação original | `422 ACCOUNT_ALIAS_NOT_IN_ORIGINAL_TRANSACTION` |
| a transação original deve existir no Midaz                     | `422 ORIGINAL_TRANSACTION_NOT_FOUND`            |

<Note>
  O endpoint, o fluxo do BTG (pacs.004 com o valor total), a idempotência e a autenticação são idênticos aos da devolução padrão. Apenas a composição do débito interno no Midaz muda.
</Note>

## Exemplo — Cappta

***

Um cash-in de R$ 50.000,00 foi dividido como R$ 49.000,00 para a conta do cliente e R$ 1.000,00 para uma conta de tarifas. Após uma fraude, a devolução exigida é de R$ 1.000,82, mas apenas R$ 0,82 restam na conta do cliente. O array `operations` debita R$ 0,82 da conta do cliente e R$ 1.000,00 da conta de tarifas, enquanto o BTG recebe uma única devolução de R$ 1.000,82 — sem necessidade de consolidação manual no ledger.

# Desbloqueio de operações presas

***

Uma devolução ou transferência cuja chamada de reversão ao BTG expira antes da confirmação pode permanecer presa em `PROCESSING`, com a retenção ainda aplicada no Midaz. Dois endpoints dedicados reconsultam o BTG e levam a operação ao seu estado terminal correto.

| Método | Endpoint                                                                                                 | Desbloqueia                                       |
| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `POST` | [`/v1/refunds/{refund_id}/unblock`](/pt/reference/midaz/plugins/indirect-pix/unblock-a-pix-refund)       | Uma devolução presa em `PROCESSING`               |
| `POST` | [`/v1/transfers/{transfer_id}/unblock`](/pt/reference/midaz/plugins/indirect-pix/unblock-a-pix-transfer) | Uma transferência presa em `PENDING`/`PROCESSING` |

Ambos exigem o cabeçalho `X-Account-Id`.

## Como o desbloqueio funciona

***

O plugin reconsulta o status da reversão/transferência no BTG e:

* Se o BTG reportar `CONFIRMED` ou `ERROR` → dispara a liquidação correspondente e move a operação para seu estado terminal.
* Se o BTG ainda reportar `INITIATED`/`PROCESSING` → retorna **HTTP 200** sem ação; tente novamente mais tarde.

Uma proteção de consistência aborta a operação se `entity`, `returnIdentification` ou `originalEndToEndId` do BTG divergirem do registro local, evitando liquidação contra a transação errada.

```json theme={null}
POST /v1/refunds/{refund_id}/unblock
X-Account-Id: <account-id>
```

A resposta inclui a `refund` atualizada, uma `message` e o `btgStatus`.

## Tratamento de um 404 do BTG

***

Quando o BTG não tem mais a reversão/transferência (retorna `404`), o comportamento depende do tipo de operação e da flag opcional `allowNotFoundUnblock` no corpo da requisição:

| Operação                                                                                                            | Padrão (estrito)                                 | Com `allowNotFoundUnblock: true`                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Transferência** ([`/v1/transfers/{id}/unblock`](/pt/reference/midaz/plugins/indirect-pix/unblock-a-pix-transfer)) | Retorna um erro                                  | Reverte a retenção no Midaz (best-effort, idempotente), marca o cashout como `FAILED` com `BTG_NOT_FOUND`, emite um webhook de saída `CASHOUT`/`TRANSFER` e retorna `200` com `btgStatus: "NOT_FOUND"` |
| **Devolução** ([`/v1/refunds/{id}/unblock`](/pt/reference/midaz/plugins/indirect-pix/unblock-a-pix-refund))         | Retorna `PIX-1012` (`ErrProviderRefundNotFound`) | Reverte a retenção e leva a devolução ao seu estado terminal                                                                                                                                           |

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

<Warning>
  `allowNotFoundUnblock` tem valor padrão `false`. Um corpo vazio/ausente ou `false` preserva o comportamento estrito (um 404 do BTG retorna um erro e nunca reverte a retenção). Só habilite quando tiver confirmado que a operação deve ser liberada.
</Warning>

<Note>
  A recuperação opcional de 404 se aplica apenas a operações `CASHOUT` em `PENDING`/`PROCESSING` com um `endToEndId` não vazio. Cash-ins e status terminais nunca entram neste fluxo.
</Note>

## Limitação intra-PSP

***

O fluxo de desbloqueio de transferência consulta o BTG pelo status, o que não se aplica a transferências intra-PSP (internas) — não há transação no BTG. Chamar o desbloqueio em uma transferência intra-PSP retorna um erro síncrono (`PIX-0418`). A lógica adequada de desbloqueio intra-PSP é um aprimoramento futuro. Consulte [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp).

# Próximos passos

***

* [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Transferências e devoluções P2P internas
* [MED 2.0 — Recuperação de Fundos](/pt/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) — Recuperação de fraude entre contas
* [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Tratamento de eventos de devolução e transferência
* [Referência da API](/pt/reference/midaz/plugins/indirect-pix/create-entry) — Documentação completa da API