1. Validation requests
| Field | Description | Used in |
|---|---|---|
| requestId | Client-generated unique ID for idempotency and audit correlation | Tracer |
| transactionType | Type of transaction: CARD, WIRE, Pix, or CRYPTO | Tracer |
| subType | Transaction subtype for additional context (e.g., debit, credit) | Tracer |
| amount | Transaction amount in cents (smallest currency unit, must be positive) | Tracer |
| currency | ISO 4217 currency code (3 uppercase letters) | Tracer |
| transactionTimestamp | When the transaction occurred (RFC 3339 format with timezone) | Tracer |
2. Validation responses
| Field | Description | Used in |
|---|---|---|
| validationId | Server-generated unique identifier for the validation record | Tracer |
| decision | Validation decision: ALLOW, DENY, or REVIEW | Tracer |
| reason | Human-readable reason for the decision | Tracer |
| matchedRuleIds | IDs of rules that matched and triggered the decision | Tracer |
| evaluatedRuleIds | IDs of all rules that were evaluated | Tracer |
| processingTimeMs | Processing time in milliseconds | Tracer |
| totalRulesLoaded | Total number of rules loaded for evaluation | Tracer |
| truncated | Whether the response was truncated due to size limits | Tracer |
3. Rules
| Field | Description | Used in |
|---|---|---|
| ruleId | Unique identifier for the rule | Tracer |
| name | Human-readable rule name (globally unique, max 255 characters) | Tracer |
| description | Rule purpose and logic explanation (max 1000 characters) | Tracer |
| expression | CEL expression that must evaluate to boolean (max 5000 characters) | Tracer |
| action | Action taken when the expression evaluates to true: ALLOW, DENY, or REVIEW | Tracer |
| scopes | Array of scopes that determine which transactions this rule applies to | Tracer |
| status | Rule lifecycle status: DRAFT, ACTIVE, INACTIVE, or DELETED | Tracer |
| activatedAt | When the rule was last activated (null if never activated) | Tracer |
| deactivatedAt | When the rule was last deactivated (null if never deactivated) | Tracer |
4. Spending limits
| Field | Description | Used in |
|---|---|---|
| limitId | Unique identifier for the limit | Tracer |
| name | Human-readable limit name (max 255 characters) | Tracer |
| description | Limit purpose and usage explanation (max 1000 characters) | Tracer |
| limitType | Type of limit: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION (immutable after creation) | Tracer |
| maxAmount | Maximum decimal amount as a string, for example "1000.00" | Tracer |
| currency | ISO 4217 currency code (immutable after creation) | Tracer |
| scopes | Array of scopes that determine which transactions this limit applies to | Tracer |
| status | Limit lifecycle status: DRAFT, ACTIVE, INACTIVE, or DELETED | Tracer |
| activeTimeStart | Start of the daily active window in HH:mm format | Tracer |
| activeTimeEnd | End of the daily active window in HH:mm format | Tracer |
| customStartDate | Start date-time for CUSTOM limits | Tracer |
| customEndDate | End date-time for CUSTOM limits | Tracer |
5. Limit usage
| Field | Description | Used in |
|---|---|---|
| limitAmount | Total limit amount in cents | Tracer |
| currentUsage | Current or projected usage after applying the transaction | Tracer |
| exceeded | Whether the limit was exceeded during validation | Tracer |
| period | Limit period type: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION | Tracer |
| scope | Human-readable scope description (e.g., “account:uuid”, “segment:uuid”) | Tracer |
| attemptedAmount | Transaction amount being validated, in cents | Tracer |
6. Scopes and targeting
| Field | Description | Used in |
|---|---|---|
| accountId | Account identifier for scope targeting | Tracer |
| segmentId | Segment identifier for scope targeting | Tracer |
| portfolioId | Portfolio identifier for scope targeting | Tracer |
| merchantId | Merchant identifier for scope targeting | Tracer |
| transactionType | Transaction type filter: CARD, WIRE, Pix, or CRYPTO | Tracer |
| category | Merchant Category Code (4-digit MCC per ISO 18245) | Tracer |
| country | Merchant country (ISO 3166-1 alpha-2, 2 uppercase letters) | Tracer |