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

# Settle fee debt (API)

> Keep the unpaid part of a deferrable fee as fee debt, then settle it from the next credit or with a collection, through the Midaz API.

Let a payment go through when the payer cannot pay the whole fee, and settle the rest of the fee later.

## Participants

***

* **Your institution.** Your system. It posts the payments and the credits, and it can collect the fee debt.
* **Midaz.** The ledger. It opens the fee debt and settles it, oldest debt first.

## Before you start

***

* The fee is deferrable: its fee package sets `deferrable` to `true` on it. Only a fee with `isDeductibleFrom` set to `false` can be deferrable.

## Diagram

***

![Settle fee debt](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-midaz-settle-fee-debt.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=8bdc87abe1963ae743bf9f82617ed6f2)

## Steps through the API

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Midaz | API call | [`POST /v2/transactions/direct`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct) | Post a payment. The payer has enough for the payment, but not for the whole fee. |
| 2 | Midaz | Midaz | Internal step | | Midaz moves the payment and the part of the fee that the payer can pay. The rest of the fee becomes fee debt. |
| 3 | Midaz | Your institution | API answer | | Midaz answers `201`. The metadata `feeDebtOpenings` lists the fee debt that the transaction opened. |
| 4 | Your institution | Midaz | API call | [`POST /v2/transactions/direct`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct) | Later, post a transaction that credits the payer. |
| 5 | Midaz | Midaz | Internal step | | Midaz uses the credit to settle the open fee debt of that balance, oldest debt first. It pays the fee account of each debt. |
| 6 | Midaz | Your institution | API answer | | Midaz answers `201`. The metadata `feeDebtSettlements` lists the debts that the credit settled. |
| 7 | Your institution | Midaz | API call | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/collect`](https://docs.lerian.studio/en/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts) | Or collect the open fee debt without a credit. Send the `accountAlias` of the payer, and optionally a `balanceKey` and a `maxAmount`. Send the `X-Idempotency` header. |
| 8 | Midaz | Your institution | API answer | | Midaz answers with the `collected` amount and the `transactionId` of the collection. |
| 9 | Your institution | Midaz | API call | [`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts`](https://docs.lerian.studio/en/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first) | Read the fee debts of the payer with `account_alias`. |
| 10 | Midaz | Your institution | API answer | | Midaz lists the debts, oldest first. `openTotal` is the total that the balance still owes. |

## Rules

***

* Only a `/v2` direct transaction opens fee debt.
* A credit to the payer through the `/v2` API can settle its open fee debt, oldest debt first, up to the amount of the credit.
* A collection charges no fee, and you cannot reverse it.

## How you know it finished

***

[List the fee debts](https://docs.lerian.studio/en/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first.md) of the payer with `account_alias` and `status=open`. The list is empty.

## What can go wrong

***

| Situation | What you see | What to do |
| - | - | - |
| The payer's balance already has 256 open fee debts | `422` with `0018` | Midaz refuses the whole payment. Collect the open fee debt or credit the payer, then post the payment again. |
| A collection settles nothing | `collected` is `0`, and there is no `transactionId` | The balance has no open debt or no available amount, or Midaz cannot move the amount between the balance and a fee account. Read the fee debts, as in step 9, and the balance. |
| You try to reverse a collection | `422` with `0089` | A collection is final. Post a new transaction if you must return an amount. |
| The answer to a collection does not arrive | No answer, or a timeout | Within the time in the `X-TTL` header (300 seconds by default), send the same collection with the same `X-Idempotency` key. After a `409` with `0084`, or after that time, read the fee debts of the payer, as in step 9, before you collect again. |

## Related

***

* [Charge a fee on a transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-charge-a-fee.md)
* [Reverse a transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-reverse-a-transaction.md)
* [Midaz error list](https://docs.lerian.studio/en/reference/products/midaz/error-list.md)


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