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

# Check Midaz transactions with Tracer (API)

> Midaz asks Tracer about a transaction before any balance moves. Tracer holds limit capacity, and Midaz confirms or releases it.

Let Midaz ask Tracer about a transaction before any balance moves.

## Participants

***

* **Your institution.** Your system creates, commits and cancels the transactions in Midaz.
* **Midaz.** The ledger. It asks Tracer before it moves any balance, and confirms or releases the capacity that Tracer holds.
* **Tracer.** Evaluates your active rules, holds capacity on your spending limits, and returns the decision to Midaz.

## Before you start

***

* Midaz is connected to Tracer in your environment.
* The Tracer mode in your ledger settings is `advisory` or `enforce`. The default is `off`. Change it with [`PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings`](https://docs.lerian.studio/en/reference/products/midaz/v2/update-ledger-settings). See [ledger settings](https://docs.lerian.studio/en/products/midaz/ledgers.md#ledger-settings).
* Your rules and spending limits are ACTIVE in Tracer. See [Set up rules and spending limits](https://docs.lerian.studio/en/diagrams/lerian-products/tracer-set-up-rules-and-limits.md).

## Diagram

***

### Transaction

![Check Midaz transactions with Tracer: Transaction](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-tracer-check-ledger-transactions-1.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=19891458a61fded0819e80d2615e0ebc)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Midaz | Lerian API | [`POST /v2/transactions/direct`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct) | Create the transaction. |
| 2 | Midaz | Tracer | Internal call | | Before any balance moves, Midaz asks Tracer to check the transaction and to hold capacity on your spending limits. |
| 3 | Tracer | Tracer | Internal step | | Tracer evaluates your active rules. If the rules do not decide `DENY` or `REVIEW`, Tracer checks your spending limits and holds the amount on the limits that count usage. |
| 4 | Tracer | Midaz | Internal call | | Tracer answers `ALLOW`, `DENY` or `REVIEW`. |
| 5 | Midaz | Midaz | Internal step | | In `enforce` mode, Midaz rejects a `DENY` or a `REVIEW`, and no balance moves. Otherwise, Midaz applies the debits and credits. |
| 6 | Midaz | Tracer | Internal call | | After the balances move, Midaz confirms the held capacity. |
| 7 | Midaz | Your institution | Lerian API | Response to step 1 | Midaz returns the transaction with `201`, or the rejection. |

### Pending transaction

![Check Midaz transactions with Tracer: Pending transaction](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-tracer-check-ledger-transactions-2.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=27f05f176653513af055dc7e92de667b)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Midaz | Lerian API | [`POST /v2/transactions/hold`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-hold) | Create a pending transaction. |
| 2 | Midaz | Tracer | Internal call | | Midaz asks Tracer to check the transaction and to hold capacity for it. |
| 3 | Tracer | Midaz | Internal call | | Tracer answers `ALLOW`, `DENY` or `REVIEW`. |
| 4 | Midaz | Your institution | Lerian API | Response to step 1 | Midaz returns the pending transaction with `201`, or the rejection. |
| 5 | Your institution | Midaz | Lerian API | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`](https://docs.lerian.studio/en/reference/products/midaz/v2/commit-transaction) or [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`](https://docs.lerian.studio/en/reference/products/midaz/v2/cancel-transaction) | Commit the pending transaction, or cancel it. |
| 6 | Midaz | Tracer | Internal call | | On a commit, Midaz confirms the held capacity. On a cancel, Midaz releases it. |
| 7 | Midaz | Your institution | Lerian API | Response to step 5 | Midaz returns the committed or canceled transaction. |

## How you know it finished

***

Midaz returned the transaction, or the committed or canceled pending transaction.

## Rules

***

* The v1 transaction routes do not call Tracer.
* In `advisory` mode, Midaz calls Tracer and never blocks the transaction.
* In `enforce` mode, when Tracer does not answer in time, `tracer.failPosture` decides. With `open`, the default, the transaction goes on without the check. With `closed`, Midaz rejects it.
* When no rule matches, Tracer does not apply the default decision on this path.
* Tracer checks the account of the first source of the transaction, with its segment and portfolio. The amount includes fees.
* Tracer receives only scalar metadata values, as text. Compare them as strings in the rules for this path.
* A revert counts against your spending limits. Tracer does not apply your rules to it.
* If a confirmation or a release does not reach Tracer, the result of the transaction does not change.
* A request can skip the Tracer check with `skip.tracer` only when the ledger setting `overrides.allowTracerSkip` is `true`.

## What can go wrong

***

The codes `0177`, `0531`, `0532`, `0535` and `0178` come only from a ledger in `enforce` mode.

| Situation | What you see | What to do |
| - | - | - |
| A limit is exceeded. | `422`, code `0177`. | Nothing moved. Reduce the amount, or wait for the limit period to reset. |
| A rule denies. | `422`, code `0535`. | Nothing moved. Review the rule that matched. |
| A rule asks for review, or Tracer cannot evaluate a rule. | `422`, code `0531`. | Nothing moved. Handle the case in your review process. |
| Tracer refuses the request. | `422`, code `0532`. | Nothing moved. Check the asset, the account type and the transaction date. |
| Tracer does not answer, and the posture is `closed`. | `503`, code `0178`. | Nothing moved. Send the transaction again later. |
| The ledger does not allow the skip. | `422`, code `0490`. | Remove `skip.tracer`, or allow the skip in the ledger settings. |
| Midaz does not answer in time. | No response. | The result is not known. Send the same request with the same `X-Idempotency` key before the key expires. |

The [Midaz error list](https://docs.lerian.studio/en/reference/products/midaz/error-list.md) describes each code.

## Related

***

* [Validate a transaction before the ledger](https://docs.lerian.studio/en/diagrams/lerian-products/tracer-validate-before-ledger.md)
* [Investigate a decision in the audit trail](https://docs.lerian.studio/en/diagrams/lerian-products/tracer-investigate-a-decision.md)
* [Tracer integration guide](https://docs.lerian.studio/en/products/tracer/integration-guide.md#midaz-ledger-reservation-seam)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.