Audit and compliance

Tracer maintains a complete, immutable audit trail of all validation decisions. This guide explains how the audit system works and how to query validation history for compliance reporting.

Compliance overview

Tracer is designed to meet the audit requirements of financial regulations including:

Regulation	Requirement	How Tracer complies
SOX (Sarbanes-Oxley)	Complete audit trail of financial decisions	Every validation is recorded with full context
GLBA (Gramm-Leach-Bliley)	Protection of customer financial data	Data encrypted at rest and in transit
General audit	Ability to reconstruct decisions	Immutable records with input/output snapshots

Audit trail architecture

What gets recorded

Every validation creates an immutable audit record containing:

Data	Description
Request snapshot	Complete input payload as received
Response snapshot	Full response including decision and details
Decision	ALLOW, DENY, or REVIEW
Reason	Why the decision was made
Evaluated rules	All rules that were evaluated
Matched rules	Rules that triggered (if any)
Limit details	Usage information for checked limits
Processing time	How long validation took
Timestamp	When the validation occurred

Immutability guarantees

Audit records are write-once:

Records cannot be modified after creation
Records cannot be deleted (except by retention policy)
Each record has a unique validation ID for reference

The audit trail is designed for compliance audits. You can reconstruct exactly what happened for any validation, even years later.

Data retention

Retention periods

Data type	Retention period	Reason
Validation records	7 years minimum	SOX/GLBA compliance requirement
Rules (active/inactive)	Indefinite	Operational continuity
Rules (deleted)	Not retained	Permanently removed
Limits	Indefinite	Operational continuity
Application logs	90 days	Debugging and troubleshooting

Compliance considerations

SOX requirement: Maintain records for 7 years from the date of the audit report
GLBA requirement: Retain records demonstrating compliance with privacy rules
Data export: Records can be exported for external audit systems

Querying validation history

Use the GET /v1/validations endpoint to query historical validations.

Basic query

GET /v1/validations
X-API-Key: {api_key}

Returns the most recent validations (last 90 days by default).

Filtered query

GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-01-31T23:59:59Z&decision=DENY
X-API-Key: {api_key}

Available filters

Parameter	Type	Description
`startDate`	RFC3339	Start of date range (inclusive)
`endDate`	RFC3339	End of date range (exclusive)
`decision`	enum	Filter by ALLOW, DENY, or REVIEW
`accountId`	UUID	Filter by account
`segmentId`	UUID	Filter by segment
`portfolioId`	UUID	Filter by portfolio
`transactionType`	enum	Filter by CARD, WIRE, PIX, CRYPTO
`matchedRuleId`	UUID	Filter by rule that matched
`exceededLimitId`	UUID	Filter by limit that was exceeded

Date format requirement

Date parameters must use RFC3339 format with mandatory timezone. Date-only formats are rejected.

Valid:

startDate=2026-01-01T00:00:00Z
startDate=2026-01-01T00:00:00-03:00

Invalid:

startDate=2026-01-01  (rejected - missing time and timezone)

Pagination

Results are paginated using cursor-based pagination:

GET /v1/validations?limit=100

Response includes a cursor for the next page:

{
  "data": [...],
  "nextCursor": "eyJpZCI6Imxhc3QtaWQifQ==",
  "hasMore": true
}

To get the next page:

GET /v1/validations?cursor=eyJpZCI6Imxhc3QtaWQifQ==

Parameter	Default	Maximum	Description
`limit`	100	1000	Results per page
`cursor`	-	-	Pagination cursor from previous response

When using cursor pagination, you cannot change sortBy or sortOrder. These are fixed from the original query.

Sorting

GET /v1/validations?sortBy=createdAt&sortOrder=DESC

Parameter	Options	Default
`sortBy`	createdAt, processingTimeMs	createdAt
`sortOrder`	ASC, DESC	DESC

Getting validation details

Retrieve complete details for a specific validation:

GET /v1/validations/{validationId}
X-API-Key: {api_key}

Response

{
  "validationId": "val-uuid-123",
  "requestId": "client-request-uuid",
  "decision": "DENY",
  "reason": "limit_exceeded",
  "request": {
    "transactionType": "CARD",
    "subType": "debit",
    "amount": 800000,
    "currency": "BRL",
    "timestamp": "2026-01-30T10:30:00Z",
    "account": {
      "accountId": "acc-uuid-123",
      "type": "checking",
      "status": "active"
    },
    "segment": {
      "segmentId": "segment-uuid-456"
    },
    "merchant": {
      "merchantId": "merchant-uuid-789",
      "category": "5411",
      "country": "BR"
    }
  },
  "response": {
    "decision": "DENY",
    "reason": "limit_exceeded",
    "matchedRuleIds": [],
    "evaluatedRuleIds": ["rule-1", "rule-2", "rule-3"],
    "limitUsageDetails": [
      {
        "limitId": "limit-uuid-123",
        "limitAmount": 5000000,
        "currentUsage": 4500000,
        "exceeded": true
      }
    ]
  },
  "processingTimeMs": 18,
  "createdAt": "2026-01-30T10:30:00.123Z"
}

This record contains everything needed to understand:

What was the input (complete request snapshot)
What was the output (complete response snapshot)
Why the decision was made
Which rules were evaluated and matched
Which limits were checked

Compliance reporting scenarios

Scenario 1: Audit investigation

“Why was this transaction denied on January 15th?”

GET /v1/validations/{validationId}

The response shows the exact request received, all rules evaluated, which rule or limit caused the denial, and the timestamp.

Scenario 2: Monthly compliance report

“Show all denied transactions for corporate accounts in January”

GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-02-01T00:00:00Z&decision=DENY&segmentId=corporate-segment-uuid&limit=1000

Scenario 3: Rule effectiveness analysis

“Which transactions were denied by a specific fraud rule?”

GET /v1/validations?matchedRuleId=fraud-rule-uuid&decision=DENY&limit=1000

Scenario 4: Limit utilization review

“Which transactions exceeded spending limits this month?”

GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-02-01T00:00:00Z&exceededLimitId=daily-limit-uuid

Best practices for compliance

Record keeping

Store validation IDs in your transaction records for easy cross-reference
Log the requestId you send to Tracer for correlation
Export regularly if you need records in external audit systems

Audit preparation

Test queries before audit season to ensure you can retrieve needed data
Verify date ranges work correctly with your timezone requirements
Document your retention policy alignment with Tracer’s 7-year retention

Investigation workflow

When investigating a specific transaction:

Find the validation ID from your transaction logs or Tracer history
Retrieve full details using GET /v1/validations/
Review the request snapshot to see what data was provided
Check matched rules to understand why the decision was made
Verify limit status if limits were involved

Fail-open behavior and audit

Tracer uses a configurable fail-open approach by default:

Scenario	Default behavior	Audit record
No rules match	ALLOW	Recorded with reason “no_match”
Database temporarily unavailable	ALLOW with warning	Recorded if possible; alert generated
Evaluation timeout	ALLOW with warning	Recorded with reason “timeout”

Fail-open behavior can be configured to fail-closed for high-security environments. Contact your administrator for configuration options.

All decisions, including those made during degraded operation, are recorded in the audit trail when possible. If a decision cannot be recorded (catastrophic failure), alerts are generated for manual review.

Quick reference

Validation history endpoint

Operation	Method	Endpoint
List validations	GET	`/v1/validations`
Get validation	GET	`/v1/validations/{validationId}`

Query parameters

Parameter	Type	Description
`startDate`	RFC3339	Start date (required timezone)
`endDate`	RFC3339	End date (required timezone)
`decision`	enum	ALLOW, DENY, REVIEW
`accountId`	UUID	Filter by account
`segmentId`	UUID	Filter by segment
`portfolioId`	UUID	Filter by portfolio
`transactionType`	enum	CARD, WIRE, PIX, CRYPTO
`matchedRuleId`	UUID	Filter by matched rule
`exceededLimitId`	UUID	Filter by exceeded limit
`limit`	integer	Results per page (max 1000)
`cursor`	string	Pagination cursor
`sortBy`	enum	createdAt, processingTimeMs
`sortOrder`	enum	ASC, DESC

Retention summary

Data	Retention
Validation records	7+ years
Active rules/limits	Indefinite
Application logs	90 days

​Compliance overview

​Audit trail architecture

​What gets recorded

​Immutability guarantees

​Data retention

​Retention periods

​Compliance considerations

​Querying validation history

​Basic query

​Filtered query

​Available filters

​Date format requirement

​Pagination

​Sorting

​Getting validation details

​Response

​Compliance reporting scenarios

​Scenario 1: Audit investigation

​Scenario 2: Monthly compliance report

​Scenario 3: Rule effectiveness analysis

​Scenario 4: Limit utilization review

​Best practices for compliance

​Record keeping

​Audit preparation

​Investigation workflow

​Fail-open behavior and audit

​Quick reference

​Validation history endpoint

​Query parameters

​Retention summary

Compliance overview

Audit trail architecture

What gets recorded

Immutability guarantees

Data retention

Retention periods

Compliance considerations

Querying validation history

Basic query

Filtered query

Available filters

Date format requirement

Pagination

Sorting

Getting validation details

Response

Compliance reporting scenarios

Scenario 1: Audit investigation

Scenario 2: Monthly compliance report

Scenario 3: Rule effectiveness analysis

Scenario 4: Limit utilization review

Best practices for compliance

Record keeping

Audit preparation

Investigation workflow

Fail-open behavior and audit

Quick reference

Validation history endpoint

Query parameters

Retention summary