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

# Liquidar a dívida de tarifa (API)

> Mantenha a parte não paga de uma tarifa diferível como dívida de tarifa e liquide-a com o próximo crédito ou com uma cobrança, pela API do Midaz.

Deixe um pagamento passar quando o pagador não pode pagar a tarifa inteira e liquide o restante da tarifa depois.

## Participantes

***

* **Sua instituição.** O seu sistema. Ele lança os pagamentos e os créditos e pode cobrar a dívida de tarifa.
* **Midaz.** O ledger. Ele abre a dívida de tarifa e a liquida, da dívida mais antiga para a mais nova.

## Antes de começar

***

* A tarifa é diferível: o pacote de tarifas define `deferrable` como `true` nela. Apenas uma tarifa com `isDeductibleFrom` em `false` pode ser diferível.

## Diagrama

***

![Liquidar a dívida de tarifa](https://mintcdn.com/lerian-49cb71fc/WuRfbo_y9uSbzyyX/images/pt/d2/id-midaz-settle-fee-debt.svg?fit=max\&auto=format\&n=WuRfbo_y9uSbzyyX\&q=85\&s=77b687a626052ffb286cdc8421bb9365)

## Passo a passo pela API

***

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | Midaz | Chamada de API | [`POST /v2/transactions/direct`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct) | Lance um pagamento. O pagador tem o suficiente para o pagamento, mas não para a tarifa inteira. |
| 2 | Midaz | Midaz | Etapa interna | | O Midaz move o pagamento e a parte da tarifa que o pagador pode pagar. O restante da tarifa vira dívida de tarifa. |
| 3 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201`. O metadado `feeDebtOpenings` lista a dívida de tarifa que a transação abriu. |
| 4 | Sua instituição | Midaz | Chamada de API | [`POST /v2/transactions/direct`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct) | Depois, lance uma transação que credita o pagador. |
| 5 | Midaz | Midaz | Etapa interna | | O Midaz usa o crédito para liquidar a dívida de tarifa aberta daquele saldo, da dívida mais antiga para a mais nova. Ele paga a conta de tarifa de cada dívida. |
| 6 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201`. O metadado `feeDebtSettlements` lista as dívidas que o crédito liquidou. |
| 7 | Sua instituição | Midaz | Chamada de API | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/collect`](https://docs.lerian.studio/pt/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts) | Ou cobre a dívida de tarifa aberta sem um crédito. Envie o `accountAlias` do pagador e, se quiser, um `balanceKey` e um `maxAmount`. Envie o header `X-Idempotency`. |
| 8 | Midaz | Sua instituição | Resposta da API | | O Midaz responde com o valor `collected` e o `transactionId` da cobrança. |
| 9 | Sua instituição | Midaz | Chamada de API | [`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts`](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first) | Leia as dívidas de tarifa do pagador com `account_alias`. |
| 10 | Midaz | Sua instituição | Resposta da API | | O Midaz lista as dívidas, da mais antiga para a mais nova. `openTotal` é o total que o saldo ainda deve. |

## Regras

***

* Apenas uma transação direta `/v2` abre dívida de tarifa.
* Um crédito ao pagador pela API `/v2` pode liquidar a dívida de tarifa aberta dele, da dívida mais antiga para a mais nova, até o valor do crédito.
* Uma cobrança não cobra tarifa, e você não pode estorná-la.

## Como saber que terminou

***

[Liste as dívidas de tarifa](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first.md) do pagador com `account_alias` e `status=open`. A lista está vazia.

## O que pode dar errado

***

| Situação | O que você vê | O que fazer |
| - | - | - |
| O saldo do pagador já tem 256 dívidas de tarifa abertas | `422` com `0018` | O Midaz recusa o pagamento inteiro. Cobre a dívida de tarifa aberta ou credite o pagador e lance o pagamento de novo. |
| Uma cobrança não liquida nada | `collected` é `0`, e não há `transactionId` | O saldo não tem dívida aberta ou não tem valor disponível, ou o Midaz não pode mover o valor entre o saldo e uma conta de tarifa. Leia as dívidas de tarifa, como no passo 9, e o saldo. |
| Você tenta estornar uma cobrança | `422` com `0089` | Uma cobrança é definitiva. Lance uma nova transação se precisar devolver um valor. |
| A resposta de uma cobrança não chega | Nenhuma resposta, ou um timeout | Dentro do tempo do header `X-TTL` (300 segundos por padrão), envie a mesma cobrança com a mesma chave `X-Idempotency`. Depois de um `409` com `0084`, ou depois desse tempo, leia as dívidas de tarifa do pagador, como no passo 9, antes de cobrar de novo. |

## Relacionados

***

* [Cobrar uma tarifa em uma transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-charge-a-fee.md)
* [Estornar uma transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-reverse-a-transaction.md)
* [Lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.