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

# Charge a fee on a transaction (API)

> Configure a fee package once and let Midaz add the fee to each matching transaction, through the Midaz 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

***

![Charge a fee on a transaction](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-midaz-charge-a-fee.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=9e06cc69097e5ed0de44f92ce51c1aab)

## 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-package) | 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-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](https://docs.lerian.studio/en/reference/products/midaz/v2/estimate-fee-calculation.md).

## 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](https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-operations-by-account.md) before you send the transaction again. |

## Related

***

* [Set up a ledger and post the first transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact.md)
* [Settle fee debt](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-settle-fee-debt.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.