Check Midaz transactions with Tracer (API)

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. See ledger settings.
Your rules and spending limits are ACTIVE in Tracer. See Set up rules and spending limits.

Diagram

Transaction

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	Lerian API	`POST /v2/transactions/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

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	Lerian API	`POST /v2/transactions/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` or `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`	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 describes each code.

Overview

Midaz

Tracer

Reporter

Check Midaz transactions with Tracer (API)

Participants

Before you start

Diagram

Transaction

Pending transaction

How you know it finished

Rules

What can go wrong

​Participants

​Before you start

​Diagram

​Transaction

​Pending transaction

​How you know it finished

​Rules

​What can go wrong

​Related

Participants

Before you start

Diagram

Transaction

Pending transaction

How you know it finished

Rules

What can go wrong

Related