Charge a fee on a transaction (API)

Charge a fee automatically on the transactions that match a fee package.

Participants

Your institution. Your system. It configures the fee package and posts the transactions.
Midaz. The ledger. It selects the package, adds the fee and posts the transaction.

Before you start

The account that receives the fee exists in the ledger. The fee names it in creditAccount.

Diagram

Steps through the API

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	API call	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages`	Create the fee package with its `feeGroupLabel`, `minimumAmount`, `maximumAmount`, `enable` and `fees`. Each fee has a `creditAccount`, the account that receives it.
2	Your institution	Midaz	API call	`POST /v2/transactions/direct`	Post the transaction. Send the `routeId` or the metadata that the package expects. Send the `X-Idempotency` header.
3	Midaz	Midaz	Internal step		Midaz selects the package that matches the transaction.
4	Midaz	Midaz	Internal step		Midaz adds the fee movements to the transaction. Each fee goes to its `creditAccount`.
5	Midaz	Midaz	Internal step		Midaz applies the payment and the fee movements together. All of the balances change, or none of them changes.
6	Midaz	Your institution	API answer		Midaz answers `201` with the transaction. The metadata `feeApplied` is `"true"`, and `packageAppliedID` names the package.

Rules

A /v1 transaction and a reversal charge no new fee.
A package applies when the transaction matches each condition that the package sets, and the amount is in the range from minimumAmount to maximumAmount. The conditions are transactionRoute, segmentId and each pair in metadataSelector.
The transaction route is the routeId of the transaction. The segment is the one that the source accounts share.
When several packages apply, the package with the most conditions wins. Midaz applies at most one package to a transaction.
With isDeductibleFrom set to false, the sources pay the fee on top of the amount. With true, the destinations receive the amount less the fee.
When each source account is in waivedAccounts, Midaz charges no fee.
To see the fee of a package before you post, use Estimate fee calculation.

How you know it finished

The transaction metadata shows feeApplied as "true" and packageAppliedID with the id of the package. Each fee operation shows the metadata feeLeg as "true".

What can go wrong

Situation	What you see	What to do
Two packages match with the same number of conditions	`400` with `0198`	Change the conditions of one of the packages. The error names them.
The payer cannot pay the amount and the fee	`422` with `0018`	Midaz moved nothing. Add funds.
No fee appears on the transaction	`201` without `feeApplied` as `"true"`	Compare the conditions of the package with the `routeId`, the metadata and the amount of the transaction.
The answer does not arrive	No answer, or a timeout	Do not assume that the transaction failed. Within the time in the `X-TTL` header (300 seconds by default), send the same request with the same `X-Idempotency` key. A `201` with `X-Idempotency-Replayed: true` returns the first transaction. A `409` with `0084` means that Midaz has no stored result for the first request yet: send it again later with the same key. After that time, read the operations of the source account before you send the transaction again.

Overview

Midaz

Tracer

Reporter

Charge a fee on a transaction (API)

Participants

Before you start

Diagram

Steps through the API

Rules

How you know it finished

What can go wrong

​Participants

​Before you start

​Diagram

​Steps through the API

​Rules

​How you know it finished

​What can go wrong

​Related

Participants

Before you start

Diagram

Steps through the API

Rules

How you know it finished

What can go wrong

Related