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. 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. On a ledger in enforce mode, Ledger HTTP v1 refuses a transaction that moves balances with 0574.
• 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 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 records each decision as a validation with the transactionId of the transaction. Find it with GET /v1/validations and transaction_id. To read the limit holds of the transaction, call GET /v1/validations/{validation_id}/reservations.
• Tracer checks the source accounts that Midaz sends, each with its segment, portfolio and the amount that leaves it, and stops at the first DENY. The amount includes fees. A source that Tracer refuses refuses the whole transaction. The validation of a transaction with more than one source lists the outcome of each source in sources.
• 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.

​

Related

---

• Validate a transaction before the ledger
• Investigate a decision in the audit trail
• Tracer integration guide