Settle fee debt (API) - Lerian

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

Steps through the API

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	API call	`POST /v2/transactions/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`	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`	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`	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 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.