Skip to main content
POST
/
v1
/
validations
Validate a Transaction
curl --request POST \
  --url https://tracer.lerian.io/v1/validations \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "CARD",
  "subType": "debit",
  "amount": 150000,
  "currency": "BRL",
  "transactionTimestamp": "2026-01-30T10:30:00Z",
  "account": {
    "accountId": "660e8400-e29b-41d4-a716-446655440001",
    "type": "checking",
    "status": "active"
  },
  "segment": {
    "segmentId": "770e8400-e29b-41d4-a716-446655440002",
    "name": "corporate"
  },
  "merchant": {
    "merchantId": "990e8400-e29b-41d4-a716-446655440004",
    "name": "Store ABC",
    "category": "5411",
    "country": "BR"
  },
  "metadata": {
    "channel": "MOBILE_APP",
    "deviceId": "device-abc123"
  }
}
'
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "validationId": "ff0e8400-e29b-41d4-a716-446655440010",
  "decision": "ALLOW",
  "reason": "Transaction approved",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "aa1e8400-e29b-41d4-a716-446655440011",
    "bb1e8400-e29b-41d4-a716-446655440012"
  ],
  "limitUsageDetails": [
    {
      "limitId": "cc1e8400-e29b-41d4-a716-446655440013",
      "limitAmount": 5000000,
      "currentUsage": 1650000,
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

Headers

​
Content-Type
string
required

The type of media of the resource. Must be application/json.

​
X-API-Key
string
required

The API Key for authentication. This header is required for all endpoints except health checks.

​
X-Request-Id
string<uuid>

A unique identifier used to trace and track each request.

Body

application/json

Transaction validation request. All context required for validation must be included (Payload-Complete Pattern).

​
requestId
string<uuid>
required

Client-generated unique ID for idempotency and audit trail correlation.

​
transactionType
enum<string>
required

Type of transaction (payment method).

Available options:
CARD,
WIRE,
PIX,
CRYPTO
​
amount
integer
required

Transaction amount in cents (smallest currency unit). Must be positive integer.

Required range: x >= 1
​
currency
string
required

ISO 4217 currency code (uppercase). Lowercase codes are rejected.

Required string length: 3
​
transactionTimestamp
string<date-time>
required

Transaction timestamp in RFC3339 format with timezone.

​
account
object
required

Account context for validation.

​
subType
string

Transaction subtype for additional context (e.g., debit, credit, prepaid).

Maximum string length: 50
​
segment
object

Segment context (optional). If provided, segmentId is required.

​
portfolio
object

Portfolio context (optional). If provided, portfolioId is required.

​
merchant
object

Merchant context (optional, recommended for card transactions). If provided, merchantId is required.

​
metadata
object

Custom key-value pairs for rule expressions.

Response

Indicates that the validation was processed successfully and returns the decision.

Transaction validation result.

​
requestId
string<uuid>

Echo of the client-provided request identifier.

​
validationId
string<uuid>

Server-generated unique identifier for this validation record.

​
decision
enum<string>

Validation decision (ALLOW, DENY, or REVIEW).

Available options:
ALLOW,
DENY,
REVIEW
​
reason
string

Human-readable reason for the decision.

​
matchedRuleIds
string<uuid>[]

IDs of rules that matched and triggered the decision.

​
evaluatedRuleIds
string<uuid>[]

IDs of all rules that were evaluated.

​
limitUsageDetails
object[]

Details about each limit checked during validation.

​
processingTimeMs
integer

Processing time in milliseconds (target < 80ms p99).

​
totalRulesLoaded
integer

Total number of rules loaded for evaluation.

​
truncated
boolean

Whether the response was truncated due to size limits.