Validate a transaction before the ledger (API)

Ask Tracer for a decision on each transaction, and post it to Midaz only after ALLOW.

Participants

Your institution. Your system collects the transaction context, calls Tracer, acts on the decision and posts the transaction.
Tracer. Evaluates your active rules and spending limits, and returns the decision. It consumes no limit.
Midaz. The ledger that records the transaction after ALLOW.

Your system can call the Tracer API with a valid credential. See the Tracer integration guide.
Your rules and spending limits are ACTIVE in Tracer. See Set up rules and spending limits.

#	From	To	Message	Lerian API	What happens
1	Your institution	Tracer	Lerian API	`POST /v1/validations`	Send the full transaction context with a new `requestId`.
2	Tracer	Tracer	Internal step		Tracer evaluates your active rules. Unless the result is already `DENY` or `REVIEW`, it checks your active spending limits.
3	Tracer	Your institution	Lerian API	Response to step 1	Tracer returns `ALLOW`, `DENY` or `REVIEW` with the `validationId`, the matched rules and the limit usage. A new request returns `201`. A known `requestId` returns `200`.
4	Your institution	Your institution	Internal step		Post the transaction after `ALLOW`. Refuse it after `DENY`. Send a `REVIEW` to your own review process.
5	Your institution	Midaz	Lerian API	`POST /v2/transactions/direct`	Post the transaction to the ledger, only after `ALLOW`.
6	Midaz	Your institution	Lerian API	Response to step 5	Midaz returns the created transaction with `201`.

Tracer returned a decision with its validationId. After ALLOW, Midaz returned the created transaction.

A matched DENY rule decides DENY, and Tracer then does not check the limits. Next, a matched REVIEW rule or a rule that Tracer cannot evaluate decides REVIEW. Then a matched ALLOW rule decides ALLOW. Last, when no rule matches and Tracer can evaluate every rule, the default decision of your Tracer configuration applies: ALLOW or DENY. Tracer then checks an ALLOW against your limits. An amount that would take a limit past its maximum decides DENY with the reason limit_exceeded.
This journey reads your spending limits and counts nothing against them. Only a transaction that Midaz creates with Tracer enabled consumes a limit. See Check Midaz transactions with Tracer.
A requestId that Tracer already knows returns the stored decision when the request is the same. A different request with that requestId, or one that the other validate route stored, returns 409 with code 0084.
To decide by your rules alone, send the same request to POST /v1/validations/rules-only.

Situation	What you see	What to do
Tracer does not answer in time.	No response.	Send the same request with the same `requestId`. Tracer returns the stored decision if it has one. If not, it decides now.
Tracer answers `409` with code `0084`.	The `requestId` is already stored for another request.	Send the request with a new `requestId`.
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.