Integration guide

Integrating Tracer means deciding where in your authorization flow to make the validation call, what data to send, and how to handle the three possible decisions. The pattern is short: your system collects the full transaction context, calls POST /v1/validations, acts on ALLOW / DENY / REVIEW, and moves on. Tracer never reaches back into your stack — there are no webhooks or callbacks; the integration ends with the response. What changes in your operation: decisioning moves from in-process logic to an external call. The call is synchronous (request/response, no webhooks), so it sits on the critical path of the transaction. Done well, it adds under 80ms p99 and gives you a single point for policy and audit. Done poorly — no timeout, no retry strategy, no fallback — it becomes a single point of failure. Trade-off to be honest about: you’re adding a network hop. The good news is the contract is simple: idempotent by requestId, no callbacks, deterministic three-state response. The bad news is you need to think about timeouts, retries, and what to do if Tracer is unreachable — most of this guide is about that.

Who is this guide for? Integration engineers writing the request from your system to Tracer, and architects deciding where the call sits in the flow. Risk and fraud analysts who write rules can skip ahead to the Rules engine guide; compliance can read the Audit and compliance guide instead.

This guide covers payload requirements, the integration flow, and practices that keep the validation call inside your latency budget. Tracer sits outside your ledger: it never calls Midaz. Your application orchestrates the two — it calls Tracer to validate, and only submits the transaction to Midaz if the decision is ALLOW. Tracer evaluates your configured policies and limits against the context you send, not account balances — the ledger stays the source of truth for what an account holds.

Midaz can also drive Tracer itself, through an optional per-ledger reservation seam that is off by default: the ledger reserves limit capacity before committing a transaction, then confirms or releases the hold. That seam still runs Midaz → Tracer; Tracer never calls out to the ledger. The rest of this guide covers the application-orchestrated pattern.

Integration overview

Tracer is designed to be called by authorization systems (payment gateways, workflow orchestrators, or transaction processors) that need real-time validation decisions. The integration follows a simple request-response pattern:

Request-response integration where an authorization system calls Tracer for a validation decision and only submits the transaction to Midaz when the decision is ALLOW — Figure 1. Integration overview with Tracer

Key principle: Tracer does not fetch external data during validation. Your system is responsible for providing all context needed for rule evaluation.

Payload-Complete Pattern

Tracer uses the Payload-Complete Pattern, which means all context required for validation must be included in the request. This design ensures:

Benefit	Description
Predictable latency	No external calls during validation; response time stays under 80ms
Simplicity	Single request contains everything needed for decision
Reliability	No dependency on external services during validation
Flexibility	Your system controls data freshness and enrichment logic

Your responsibilities

As the integrating system, you are responsible for:

Enriching the payload with account, segment, portfolio, and merchant data before calling Tracer
Providing accurate context for rule and limit evaluation—Tracer cannot fetch missing data
Handling the decision (ALLOW, DENY, or REVIEW) appropriately in your workflow
Implementing retry logic if Tracer is temporarily unavailable
Managing review workflows when Tracer returns REVIEW—Tracer does not include case management

Tracer validates what you send. If your payload is missing context (e.g., account status, segment membership), rules that depend on that data cannot evaluate correctly. Always ensure payloads are complete before submission.

Tracer’s responsibilities

Tracer is responsible for:

Evaluating rules against the provided context
Checking limits against current usage
Recording audit trail for compliance
Returning decision with detailed information

Integration flow

Follow these steps to integrate your system with Tracer.

Step 1: Prepare the transaction context

Before calling Tracer, gather all relevant data from your systems:

Steps for preparing the transaction context and calling Tracer, from gathering data in your systems to acting on the returned decision — Figure 2. Preparing transaction context

Step 2: Call Tracer API

Send a POST request to /v1/validations with the complete transaction context including:

Transaction details (type, subType, amount, currency, timestamp)
Account information (required)
Optional: segment, portfolio, merchant, and custom

For complete payload structure and field details, see the API reference.

Step 3: Handle the response

Process the decision returned by Tracer:

Decision	Action
`ALLOW`	Proceed with the transaction
`DENY`	Reject the transaction; show reason to user if appropriate
`REVIEW`	Queue for manual review in your review system

The response includes the validationId for audit trail correlation, details about which rules matched, and current limit usage information.

Using metadata

Metadata allows you to pass custom fields that your rules can evaluate. Use this for context like channel, device information, customer tier, or any business-specific attributes.

Metadata keys must be alphanumeric with underscores only, maximum 64 characters. Maximum 50 entries per request.

Request idempotency

Validation requests are idempotent based on the requestId field. If you send the same requestId twice, Tracer returns the cached result from the first request instead of reprocessing.

Response code	Meaning
`201 Created`	New validation processed
`200 OK`	Duplicate request detected; cached result returned

The response body is identical in both cases. Your client should handle both status codes as success. Why it matters: Network timeouts and retries can cause duplicate requests. Without idempotency, a retried request could double-count against limits or create duplicate audit records. The requestId ensures exactly-once processing semantics. Idempotency contract:

Same requestId → Same response (guaranteed)
Different requestId → Independent processing (even if transaction data is identical)

Always generate a unique requestId (UUID) for each new transaction. Reusing a requestId from a previous transaction will return the old result, not process the new transaction.

Authentication

Tracer supports two authentication modes that can be used independently or combined.

API key authentication

The simplest option. Send your API key in the X-API-Key header with every request.

Environment variable	Description
`API_KEY_ENABLED`	Enable API key authentication (default: `false`)
`API_KEY`	The secret key value
`API_KEY_ENABLED_ONLY_VALIDATION`	Use API key only for the `/v1/validations` endpoint (default: `false`)

Plugin authentication (Access Manager)

For enterprise deployments, Tracer can delegate authentication to the Lerian Access Manager. This enables centralized authentication across all Lerian services.

Environment variable	Description
`PLUGIN_AUTH_ENABLED`	Enable plugin authentication (default: `false`)
`PLUGIN_AUTH_ADDRESS`	URL of the auth service (default: `http://localhost:4000`)

Authentication priority

When both modes are enabled, Tracer uses this priority:

If PLUGIN_AUTH_ENABLED=true and the endpoint is not flagged for API-key-only → Plugin auth
If API_KEY_ENABLED=true or the endpoint is flagged for API-key-only → API key auth

Infrastructure endpoints (health checks, version probe, OpenAPI spec) bypass authentication and are not part of the public /v1/* API surface documented in this reference.

The /v1/validations endpoint can be configured for API-key-only authentication via API_KEY_ENABLED_ONLY_VALIDATION=true. This is useful in high-throughput scenarios where plugin auth adds unacceptable latency. This flag is incompatible with multi-tenant mode (MULTI_TENANT_ENABLED=true) — the service fails to start with error code 0458.

Multi-tenant authentication

When MULTI_TENANT_ENABLED=true, Tracer runs in multi-tenant mode and the authentication model changes:

Plugin auth is required. The service fails to start with error code 0457 if PLUGIN_AUTH_ENABLED=false.
Every /v1/* request must carry a JWT bearer token issued by Access Manager: Authorization: Bearer <jwt>.
tenantId is resolved from the JWT claim, not from a header, path, body, metadata, or rule scope. There is no X-Tenant-ID header — passing the tenant identifier anywhere other than the token claim is unsupported and ignored.
Each tenant operates on its own PostgreSQL database. The tenant-specific connection is resolved by the multi-tenancy platform service at request time.
Public endpoints (/health, /readyz, /metrics, /version) stay unauthenticated in multi-tenant mode too — the bearer-token requirement applies only to /v1/*.

If the JWT is missing, malformed, or expired, the request returns HTTP 401 with "code": "Unauthenticated" (the same code used for missing API keys; no separate TRC code is emitted). One case is distinct: a token that parses but carries no sub claim is rejected up front with HTTP 401 and error code 0474. sub is what the audit writer uses to attribute the action to a principal, so Tracer fails loudly rather than recording the change against a generic system actor — make sure your Access Manager tokens always carry it. If the multi-tenant deployment hits its per-instance tenant cap, requests for cold tenants return HTTP 503 with error code 0466 and a Retry-After header. The client should back off and retry; the cap auto-resets as the LRU pool evicts cold tenants. See Multi-tenancy for the platform-wide tenant model.

Performance considerations

Optimize your integration for low latency and high reliability.

Timeout budget

Tracer is designed to respond in under 80ms (p99). Configure your client timeout accordingly:

Configuration	Recommended value
Client timeout	100ms
Connection timeout	50ms
Read timeout	100ms

Retry strategy

Implement retry logic for transient failures:

On 5xx error or timeout:
  - Wait 10ms
  - Retry once
  - If still failing, apply fallback policy

Do not retry on 4xx errors—these indicate invalid requests that will fail again. For retries on 5xx/timeout, reuse the same requestId to take advantage of idempotency.

Fallback behavior

Decide what happens when Tracer is unavailable:

Strategy	When to use
Fail-open	Allow transaction if Tracer is down (prioritize availability)
Fail-closed	Deny transaction if Tracer is down (prioritize security)
Queue for review	Queue transaction for manual review

Your choice depends on your risk tolerance and business requirements.

Common integration pitfalls:

“My retry created a duplicate validation in the audit trail.” Reuse the same requestId across retries. Tracer deduplicates by that field — the second call returns the cached result (HTTP 200) without creating a duplicate event. If you generate a fresh UUID on every retry, you defeat idempotency.
“My client times out after 30 seconds but Tracer keeps processing.” Tracer respects its own deadlines (~80ms p99 target). If your client gives up on the call, Tracer’s work is already wasted on returning a response. Set client timeout aggressively (100ms) and trust the retry path.
“My validation is rejected with error code 0421 (timestamp too old) on legitimate transactions.” Default tolerance is 24 hours. Check your server clock and the transactionTimestamp you’re sending — if you batch-process late, you need to set the timestamp to the actual transaction moment, not the moment you’re calling Tracer.
“Test transactions show up in production audit.” All validations are recorded, including from test/staging environments calling the same Tracer instance. Use metadata.environment (or similar) to tag and filter test traffic if you share Tracer between environments.

Data freshness

Since you control the payload enrichment, data freshness is your responsibility. Tracer trusts the data you provide and cannot detect stale information.

Data type	Freshness recommendation	Risk if stale
Account status	Real-time or near real-time	Transactions on suspended accounts may be allowed
Segment membership	Can be cached (changes infrequently)	Wrong limits or rules may apply
Portfolio assignment	Can be cached (changes infrequently)	Incorrect scope matching
Merchant data	Can be cached with periodic refresh	Risk rules may not trigger correctly

Stale data leads to incorrect decisions. If an account was suspended but your cache shows it as active, Tracer will allow transactions that should be denied. Your enrichment layer is the source of truth for Tracer.

Date and time format

All datetime fields must use RFC3339 format with mandatory timezone: Valid formats:

2026-01-30T10:30:00Z           (UTC)
2026-01-30T10:30:00-03:00      (São Paulo timezone)
2026-01-30T00:00:00+00:00      (UTC explicit)

Invalid formats:

2026-01-30                     (date only - rejected)
2026-01-30T10:30:00            (missing timezone - rejected)

Integration checklist

Before going to production, verify:

Example integration (pseudocode)

def validate_transaction(transaction):
    # Step 1: Enrich payload
    payload = {
        "requestId": generate_uuid(),
        "transactionType": transaction.type,
        "amount": transaction.amount,
        "currency": transaction.currency.upper(),
        "transactionTimestamp": now_rfc3339(),
        "account": get_account_context(transaction.account_id),
        "segment": get_segment_context(transaction.segment_id),
        "merchant": get_merchant_context(transaction.merchant_id),
        "metadata": transaction.custom_fields
    }

    # Step 2: Call Tracer
    try:
        response = http_post(
            url="https://tracer.example.com/v1/validations",
            headers={"X-API-Key": API_KEY},
            json=payload,
            timeout_ms=100
        )
    except Timeout:
        return apply_fallback_policy()
    except ServerError:
        return retry_once_or_fallback()

    # Step 3: Handle decision
    if response.decision == "ALLOW":
        return proceed_with_transaction()
    elif response.decision == "DENY":
        return reject_transaction(response.reason)
    elif response.decision == "REVIEW":
        return queue_for_manual_review(response.validationId)

Next steps

Rules engine - Create rules that evaluate against the context you provide
Spending limits - Configure limits that apply to your transaction scopes
Audit and compliance - Query validation history and audit trail

Overview

Guides

Console

Operations

Integration guide

Integration overview

Payload-Complete Pattern

Your responsibilities

Tracer’s responsibilities

Integration flow

Step 1: Prepare the transaction context

Step 2: Call Tracer API

Step 3: Handle the response

Using metadata

Request idempotency

Authentication

API key authentication

Plugin authentication (Access Manager)

Authentication priority

Multi-tenant authentication

Performance considerations

Timeout budget

Retry strategy

Fallback behavior

Data freshness

Date and time format

Integration checklist

Example integration (pseudocode)

Next steps

​Integration overview

​Payload-Complete Pattern

​Your responsibilities

​Tracer’s responsibilities

​Integration flow

​Step 1: Prepare the transaction context

​Step 2: Call Tracer API

​Step 3: Handle the response

​Using metadata

​Request idempotency

​Authentication

​API key authentication

​Plugin authentication (Access Manager)

​Authentication priority

​Multi-tenant authentication

​Performance considerations

​Timeout budget

​Retry strategy

​Fallback behavior

​Data freshness

​Date and time format

​Integration checklist

​Example integration (pseudocode)

​Next steps

Integration overview

Payload-Complete Pattern

Your responsibilities

Tracer’s responsibilities

Integration flow

Step 1: Prepare the transaction context

Step 2: Call Tracer API

Step 3: Handle the response

Using metadata

Request idempotency

Authentication

API key authentication

Plugin authentication (Access Manager)

Authentication priority

Multi-tenant authentication

Performance considerations

Timeout budget

Retry strategy

Fallback behavior

Data freshness

Date and time format

Integration checklist

Example integration (pseudocode)

Next steps