Make a fee deferrable
Set
deferrable: true on a fee when you create or update its fee package.
- Only a fee with
isDeductibleFrom: falsecan be deferrable. Midaz refuses a deductible fee that is also deferrable with error0530. - A deferrable fee opens a debt only in a
/v2direct transaction. In a/v2hold, Midaz refuses an unfunded fee with error0018. - When a balance already has 256 open fee debts, Midaz refuses a new unfunded deferrable fee on it with error
0018.
feeDebtOpenings records the debt.
How a debt is settled
A credit to the payer’s balance through the
/v2 API can settle its open fee debts, oldest first. This includes direct transactions, commits, and reversals. A credit that is smaller than a debt settles part of it. A payer’s balance that cannot send funds settles nothing, and settlement stops at the first debt whose fee account cannot receive funds.
Each settlement moves the value from the payer’s balance to the fee account of the debt. Midaz records these movements as operations of type FEE_SETTLEMENT, and the transaction metadata key feeDebtSettlements records the settled debts.
To settle debts without a credit, use Collect open fee debts. Send the accountAlias of the payer, and optionally a balanceKey and a maxAmount.
- Midaz pays the open debts of that balance from its available amount, oldest first, and charges no fee on the collection.
- The response gives the
collectedamount and thetransactionIdof the collection. - When nothing is collected, the response gives
collected: "0"and Midaz creates no transaction. - You cannot revert a collection. Midaz refuses it with error
0089.
Reversals and fee debt
When you revert the transaction that opened a debt, the payer gets the whole fee back:
- The reversal returns the part of the fee that the payer paid in the original transaction.
- Midaz cancels the part of the debt that is still open.
- Midaz refunds the part that later credits settled. The fee account pays the refund, and Midaz records it as operations of type
FEE_REFUND. On/v2, the refund can then settle the payer’s other open debts, oldest first.
0529 (HTTP 409) and moves nothing. Try again later.
Read fee debts
- List fee debts gives the debts of a ledger, oldest first. Filter by
account_alias,balance_key, andstatus(openorsettled). Withaccount_alias, the response also givesopenTotal, the total that the balance owes. - Retrieve a fee debt gives one debt with its
remainingamount and its history of changes. - In the Console, the Fee Debts page lists the fee debts of a ledger.
midaz/fee-debts permission with get. Collecting fee debt needs post.
Each change has one of these kinds:
Accounts and balances with fee debt
Midaz refuses to delete a balance, or to delete or close its account, when:
- The balance owes fee debt (error
0527). Credit the balance or collect the debt first. - Other balances owe fee debt to the balance (error
0528), for example a fee account. Credit the balances that owe the debt first.
Before you enable fee debt
- Run Midaz v4.2.0 or later on every ledger instance before you set
deferrableon a fee. An earlier version cannot complete a transaction that carries fee debt. After you set it, do not roll the ledger back to an earlier version. - The ledger keeps open fee debts in Valkey. Valkey must be persistent and keep these keys. See Configuring dependencies.

