Skip to main content
By default, Midaz refuses a transaction when the payer cannot fund its fees. A deferrable fee changes this. The payer pays the part of the fee that its available amount covers. The rest becomes a fee debt, and the transaction goes through. Later credits to the payer settle the debt. Fee debt is off by default. It applies only to fees that you mark as deferrable.

​
Make a fee deferrable

Set deferrable: true on a fee when you create or update its fee package.
  • Only a fee with isDeductibleFrom: false can be deferrable. Midaz refuses a deductible fee that is also deferrable with error 0530.
  • A deferrable fee opens a debt only in a /v2 direct transaction. In a /v2 hold, Midaz refuses an unfunded fee with error 0018.
  • When a balance already has 256 open fee debts, Midaz refuses a new unfunded deferrable fee on it with error 0018.
Example. A payer holds 105 and sends 100 with a deferrable fee of 10. The transaction moves 105: the payment of 100 and 5 of the fee. The other 5 becomes a fee debt. The transaction metadata key feeDebtOpenings records the debt.

​
How a debt is settled

A credit to the payer’s balance through the /v2 API settles 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. 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 collected amount and the transactionId of 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 then settles the payer’s other open debts, oldest first.
A revert of a credit that settled a debt can reopen that debt for the settled amount. When the fee-debt record of a transaction is not complete yet, Midaz refuses the revert with error 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, and status (open or settled). With account_alias, the response also gives openTotal, the total that the balance owes.
  • Retrieve a fee debt gives one debt with its remaining amount and its history of changes.
Listing and reading fee debts needs the 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 deferrable on 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.