> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Validate a Transaction > Use this endpoint to validate a transaction against configured rules and limits in real-time. Returns a decision (ALLOW, DENY, or REVIEW) along with details about which rules matched and limit usage. Performance target is under 80ms (p99). ## OpenAPI ````yaml /en/openapi/v3-current/tracer.yaml post /v1/validations openapi: 3.1.0 info: title: Tracer API description: >- Complete API reference for Tracer services including transaction validation, rules management, spending limits, and audit events for SOX/GLBA compliance. version: 1.0.0 servers: - url: https://tracer.lerian.io security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Health API description: >- Health check endpoints for liveness and readiness probes. These endpoints do not require authentication. - name: Validations API description: >- Transaction validation endpoints. Performance target is under 80ms (p99). Validations are idempotent by `requestId` — a duplicate request returns the cached result with HTTP 200, while a new request returns HTTP 201. No idempotency header is required. - name: Rules API description: >- Validation rule management endpoints. Rules use CEL (Common Expression Language) expressions. - name: Limits API description: >- Spending limit management endpoints. Limits control transaction amounts by scope and period. - name: Audit Events API description: >- Audit trail endpoints for SOX/GLBA compliance. All validation decisions and configuration changes are recorded. paths: /v1/validations: post: tags: - Validations API summary: Validate a Transaction description: >- Use this endpoint to validate a transaction against configured rules and limits in real-time. Returns a decision (ALLOW, DENY, or REVIEW) along with details about which rules matched and limit usage. Performance target is under 80ms (p99). operationId: validateTransaction parameters: - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XApiKey' - $ref: '#/components/parameters/XRequestId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ValidationRequest' example: requestId: 019c96a0-10ce-75fc-a273-dc799079a99c transactionType: CARD subType: debit amount: '1500.00' currency: BRL transactionTimestamp: '2026-01-30T10:30:00Z' account: accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 type: checking status: active segment: segmentId: 019c96a0-0b4e-7079-8be0-ab6bdccf975f name: corporate merchant: merchantId: 019c96a0-4f70-7678-e1f2-7b8c9d0e1f2a name: Store ABC category: '5411' country: BR metadata: channel: MOBILE_APP deviceId: device-abc123 responses: '200': description: >- Duplicate request detected (idempotent replay). Returns the cached validation result from the original request. The response body is identical to the original 201 response. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' example: requestId: 019c96a0-10ce-75fc-a273-dc799079a99c validationId: 019c96a0-10d2-7193-8841-0d7347efd09a decision: ALLOW reason: Transaction approved matchedRuleIds: [] evaluatedRuleIds: - 019c96a0-1071-7a0d-9916-a831221de252 - 019c96a0-4b30-7234-a1b2-3d4e5f6a7b8c limitUsageDetails: - limitId: 019c96a0-0c0d-7915-84b9-e497bfee9916 limitAmount: '50000.00' currentUsage: '16500.00' exceeded: false period: DAILY processingTimeMs: 23 '201': description: >- Validation processed successfully. Returned for new validation requests (unique requestId). content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' example: requestId: 019c96a0-10ce-75fc-a273-dc799079a99c validationId: 019c96a0-10d2-7193-8841-0d7347efd09a decision: ALLOW reason: Transaction approved matchedRuleIds: [] evaluatedRuleIds: - 019c96a0-1071-7a0d-9916-a831221de252 - 019c96a0-4b30-7234-a1b2-3d4e5f6a7b8c limitUsageDetails: - limitId: 019c96a0-0c0d-7915-84b9-e497bfee9916 limitAmount: '50000.00' currentUsage: '16500.00' exceeded: false period: DAILY processingTimeMs: 23 '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0001: $ref: '#/components/examples/Error0001' Error0003: $ref: '#/components/examples/Error0003' Error0060: $ref: '#/components/examples/Error0060' Error0063: $ref: '#/components/examples/Error0063' Error0064: $ref: '#/components/examples/Error0064' Error0089: $ref: '#/components/examples/Error0089' Error0220: $ref: '#/components/examples/Error0220' Error0221: $ref: '#/components/examples/Error0221' Error0222: $ref: '#/components/examples/Error0222' Error0223: $ref: '#/components/examples/Error0223' Error0224: $ref: '#/components/examples/Error0224' Error0225: $ref: '#/components/examples/Error0225' Error0226: $ref: '#/components/examples/Error0226' Error0227: $ref: '#/components/examples/Error0227' Error0228: $ref: '#/components/examples/Error0228' Error0230: $ref: '#/components/examples/Error0230' Error0231: $ref: '#/components/examples/Error0231' Error0232: $ref: '#/components/examples/Error0232' Error0233: $ref: '#/components/examples/Error0233' Error0234: $ref: '#/components/examples/Error0234' Error0235: $ref: '#/components/examples/Error0235' Error0236: $ref: '#/components/examples/Error0236' Error0237: $ref: '#/components/examples/Error0237' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorUnauthenticated: $ref: '#/components/examples/ErrorUnauthenticated' '413': description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0011: $ref: '#/components/examples/Error0011' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0004: $ref: '#/components/examples/Error0004' Error0103: $ref: '#/components/examples/Error0103' Error0136: $ref: '#/components/examples/Error0136' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0012: $ref: '#/components/examples/Error0012' '504': description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0229: $ref: '#/components/examples/Error0229' components: parameters: ContentType: name: Content-Type in: header description: The type of media of the resource. Must be `application/json`. required: true example: application/json schema: type: string XApiKey: name: X-API-Key in: header description: >- The API Key for authentication. **This header is required for all endpoints except health checks**. required: true schema: type: string XRequestId: name: X-Request-Id in: header description: A unique identifier used to trace and track each request. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string format: uuid schemas: ValidationRequest: type: object description: >- Transaction validation request. All context required for validation must be included (Payload-Complete Pattern). required: - requestId - transactionType - amount - currency - transactionTimestamp - account properties: requestId: type: string format: uuid description: >- Client-generated unique ID for idempotency and audit trail correlation. transactionType: type: string enum: - CARD - WIRE - PIX - CRYPTO description: Type of transaction (payment method). subType: type: string maxLength: 50 description: >- Transaction subtype for additional context (e.g., debit, credit, prepaid). amount: type: string description: >- Transaction amount as a decimal string (e.g., "1500.00"). Must be a positive decimal value. currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code (uppercase). Lowercase codes are rejected. transactionTimestamp: type: string format: date-time description: Transaction timestamp in RFC3339 format with timezone. account: $ref: '#/components/schemas/AccountContext' segment: $ref: '#/components/schemas/SegmentContext' portfolio: $ref: '#/components/schemas/PortfolioContext' merchant: $ref: '#/components/schemas/MerchantContext' metadata: type: object additionalProperties: true description: Custom key-value pairs for rule expressions. ValidationResponse: type: object description: Transaction validation result. properties: requestId: type: string format: uuid description: Echo of the client-provided request identifier. validationId: type: string format: uuid description: Server-generated unique identifier for this validation record. decision: type: string enum: - ALLOW - DENY - REVIEW description: Validation decision (ALLOW, DENY, or REVIEW). reason: type: string description: Human-readable reason for the decision. matchedRuleIds: type: array items: type: string format: uuid description: IDs of rules that matched and triggered the decision. evaluatedRuleIds: type: array items: type: string format: uuid description: IDs of all rules that were evaluated. limitUsageDetails: type: array items: $ref: '#/components/schemas/LimitUsageDetail' description: Details about each limit checked during validation. processingTimeMs: type: number format: double description: Processing time in milliseconds (target < 80ms p99). evaluatedAt: type: string format: date-time description: Server timestamp when the evaluation started, in RFC3339 format. totalRulesLoaded: type: integer description: Total number of rules loaded for evaluation. truncated: type: boolean description: Whether the response was truncated due to size limits. ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. fields: type: object additionalProperties: true description: Additional information about the fields that caused the error. AccountContext: type: object description: Account context for validation. required: - accountId properties: accountId: type: string format: uuid description: Account identifier (required). type: type: string description: Account type. enum: - checking - savings - credit status: type: string description: Account status. enum: - active - suspended - closed metadata: type: object additionalProperties: true description: Additional account attributes for rule evaluation. SegmentContext: type: object description: Segment context (optional). If provided, segmentId is required. properties: segmentId: type: string format: uuid description: Segment identifier (required if segment object provided). name: type: string description: Segment name for rule expressions. metadata: type: object additionalProperties: true description: Additional segment attributes for rule evaluation. PortfolioContext: type: object description: Portfolio context (optional). If provided, portfolioId is required. properties: portfolioId: type: string format: uuid description: Portfolio identifier (required if portfolio object provided). name: type: string description: Portfolio name for rule expressions. metadata: type: object additionalProperties: true description: Additional portfolio attributes for rule evaluation. MerchantContext: type: object description: >- Merchant context (optional, recommended for card transactions). If provided, merchantId is required. properties: merchantId: type: string format: uuid description: Merchant identifier (required if merchant object provided). name: type: string description: Merchant name. category: type: string description: Merchant Category Code (MCC). Must be a 4-digit code per ISO 18245. pattern: ^[0-9]{4}$ country: type: string description: >- Merchant country. Must be ISO 3166-1 alpha-2 code (2 uppercase letters). pattern: ^[A-Z]{2}$ metadata: type: object additionalProperties: true description: Additional merchant attributes for rule evaluation. LimitUsageDetail: type: object description: Details about a limit check during validation. properties: limitId: type: string format: uuid description: The limit that was checked. limitAmount: type: string description: Total limit amount as a decimal string (e.g., "50000.00"). currentUsage: type: string description: >- Projected usage after applying transaction, as a decimal string. When exceeded, shows what usage would have been if allowed. exceeded: type: boolean description: >- Whether the limit was exceeded. When true, the counter was not incremented. period: type: string description: Limit period type. enum: - DAILY - WEEKLY - MONTHLY - CUSTOM - PER_TRANSACTION scope: type: string description: >- Human-readable scope (e.g., "account:uuid", "segment:uuid", or "global"). attemptedAmount: type: string description: Transaction amount being validated, as a decimal string. skipped: type: boolean description: >- Whether this limit was skipped during evaluation (not enforced). When true, the counter was not incremented and `exceeded` is always false. Omitted when false. skipReason: type: string enum: - outside_time_window - outside_custom_period description: Reason the limit was skipped. Only present when `skipped` is true. examples: Error0001: summary: Generic Validation Error value: code: TRC-0001 title: Validation Error message: >- Field validation failed. Please verify the provided data and try again. Error0003: summary: Invalid Request Body value: code: TRC-0003 title: Invalid Request Body message: >- The request body is invalid or malformed. Please verify the JSON format and try again. Error0060: summary: Metadata Key Too Long value: code: TRC-0060 title: Metadata Key Too Long message: >- The metadata key exceeds the maximum length of 64 characters. Please reduce the key size. Error0063: summary: Metadata Exceeds Maximum Entries value: code: TRC-0063 title: Metadata Exceeds Maximum Entries message: >- The metadata exceeds the maximum of 50 entries. Please reduce the number of entries. Error0064: summary: Metadata Key Contains Invalid Characters value: code: TRC-0064 title: Invalid Metadata Key message: >- The metadata key contains invalid characters. Only alphanumeric characters and underscore are allowed. Error0089: summary: Amount Exceeds CEL Precision value: code: TRC-0089 title: Amount Exceeds CEL Precision message: >- The amount exceeds the safe precision for CEL evaluation (maximum ±2^53). Please reduce the amount. Error0220: summary: Request ID Required value: code: TRC-0220 title: Missing Required Field message: >- The requestId field is required. Please provide a unique UUID for the request. Error0221: summary: Invalid Transaction Type value: code: TRC-0221 title: Invalid Transaction Type message: >- The transactionType must be one of CARD, WIRE, PIX, or CRYPTO. Please provide a valid transaction type. Error0222: summary: Amount Must Be Positive value: code: TRC-0222 title: Invalid Amount message: >- The amount must be a positive decimal value (e.g., "1500.00"). Please provide a valid amount. Error0223: summary: Currency Required value: code: TRC-0223 title: Missing Required Field message: >- The currency field is required. Please provide a valid ISO 4217 currency code. Error0224: summary: Invalid Currency value: code: TRC-0224 title: Invalid Currency message: >- The currency must be a valid uppercase ISO 4217 code (e.g., BRL, USD). Lowercase codes are not accepted. Error0225: summary: Transaction Timestamp Required value: code: TRC-0225 title: Missing Required Field message: >- The transactionTimestamp field is required. Please provide a timestamp in RFC3339 format. Error0226: summary: Future Timestamp Not Allowed value: code: TRC-0226 title: Future Timestamp Not Allowed message: >- The transactionTimestamp cannot be in the future. Please provide a valid timestamp. Error0227: summary: Account Required value: code: TRC-0227 title: Missing Required Field message: >- The account field is required. Please provide account context for the validation. Error0228: summary: Past Timestamp Not Allowed value: code: TRC-0228 title: Past Timestamp Not Allowed message: >- The transactionTimestamp is too far in the past. Please provide a more recent timestamp. Error0230: summary: Segment ID Required value: code: TRC-0230 title: Missing Required Field message: >- The segment.id field is required when the segment object is provided. Please provide the segment ID. Error0231: summary: Portfolio ID Required value: code: TRC-0231 title: Missing Required Field message: >- The portfolio.id field is required when the portfolio object is provided. Please provide the portfolio ID. Error0232: summary: SubType Exceeds Maximum Length value: code: TRC-0232 title: SubType Too Long message: >- The subType field exceeds the maximum length of 50 characters. Please reduce the size. Error0233: summary: Invalid Account Type value: code: TRC-0233 title: Invalid Account Type message: >- The account.type must be one of checking, savings, or credit. Please provide a valid type. Error0234: summary: Invalid Account Status value: code: TRC-0234 title: Invalid Account Status message: >- The account.status must be one of active, suspended, or closed. Please provide a valid status. Error0235: summary: Invalid Merchant Category value: code: TRC-0235 title: Invalid Merchant Category message: >- The merchant.category must be a 4-digit MCC code. Please provide a valid category. Error0236: summary: Invalid Merchant Country value: code: TRC-0236 title: Invalid Merchant Country message: >- The merchant.country must be an ISO 3166-1 alpha-2 code (e.g., BR, US). Please provide a valid country code. Error0237: summary: Merchant ID Required value: code: TRC-0237 title: Missing Required Field message: >- The merchant.id field is required when the merchant object is provided. Please provide the merchant ID. ErrorUnauthenticated: summary: Unauthorized value: code: Unauthenticated title: Unauthorized message: >- API Key missing or invalid. Provide a valid API Key in the X-API-Key header. Error0011: summary: Payload Too Large value: code: TRC-0011 title: Payload Too Large message: >- The request payload exceeds the maximum size limit of 100KB. Please reduce the payload size and try again. Error0004: summary: Internal Server Error value: code: TRC-0004 title: Internal Server Error message: >- An unexpected error occurred. Please try again later or contact support if the issue persists. Error0103: summary: Rule Evaluation Failed value: code: TRC-0103 title: Internal Server Error message: Rule evaluation failed. Please try again or contact support. Error0136: summary: Limit Check Failed value: code: TRC-0136 title: Internal Server Error message: Limit check failed. Please try again or contact support. Error0012: summary: Service Unavailable value: code: TRC-0012 title: Service Unavailable message: >- The service is temporarily unavailable or the request was cancelled. Please try again later. Error0229: summary: Validation Timeout value: code: TRC-0229 title: Gateway Timeout message: >- The validation processing exceeded the 80ms budget. Please try again or contact support if the issue persists. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API Key authentication. Used by single-tenant deployments (`MULTI_TENANT_ENABLED=false`). Sent on every `/v1/*` request. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer authentication. Used by multi-tenant deployments (`MULTI_TENANT_ENABLED=true`). The JWT is issued by Access Manager and must carry the `tenantId` claim — Tracer resolves the tenant from the token, not from any header or body field. ````