openapi: 3.1.0 info: title: Thales Credit Core External API version: v1 description: Official external server-to-server API contract. This artifact excludes Admin, UI/reference, test-only, controlled CSV, health disclosure, client-info, and incomplete account-history operations. servers: - url: https://thales-credit-core-test.hamed-saffarian.workers.dev description: Test API environment. Use Test credentials only. - url: https://production-api.example.invalid description: Production URL pending approved provisioning; replace this documented placeholder before Production publication. tags: - name: Customers - name: Accounts - name: Transactions - name: Reservations - name: Rewards paths: /v1/customers: post: operationId: customer_create tags: - Customers summary: Create a customer with external identities and one zero-balance credit account. description: Requires API-key authentication and scope `customers:create`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/CustomerCreateResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: customer_id: cust_test_example_01 account_id: acct_test_example_01 account_reference: acct_test_01J8Q4M2K7 customer_status: ACTIVE account_status: ACTIVE current_balance_tc: 0 reserved_balance_tc: 0 available_balance_tc: 0 created_at: 2026-08-04T10:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/CustomerCreateResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: customer_id: cust_test_example_01 account_id: acct_test_example_01 account_reference: acct_test_01J8Q4M2K7 customer_status: ACTIVE account_status: ACTIVE current_balance_tc: 0 reserved_balance_tc: 0 available_balance_tc: 0 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE message: The API client lacks the required scope. "404": description: "Errors: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE message: The request cannot be processed with the supplied values. "409": description: "Errors: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: INVALID_IDENTITY_STATUS" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_IDENTITY_STATUS error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_IDENTITY_STATUS message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: customers:create x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESOURCE_NOT_FOUND - IDENTITY_CONFLICT - INVALID_IDENTITY_STATUS - RATE_LIMITED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - END_USER_ACCESS_UNAVAILABLE x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomerCreateRequest" /v1/customers/lookup: get: operationId: customer_lookup tags: - Customers summary: Look up a customer by an exact external identity. description: Requires API-key authentication and scope `customers:read`. security: - apiKey: [] parameters: - name: type in: query required: true schema: type: string enum: - XT_UID - TELEGRAM_ID - EMAIL - WEBSITE_USER_ID - CRM_ID example: XT_UID - name: value in: query required: true schema: type: string example: "1000123456" responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/CustomerLookupResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: customer_id: cust_test_example_01 account_id: acct_test_example_01 account_reference: acct_test_01J8Q4M2K7 customer_status: ACTIVE account_status: ACTIVE current_balance_tc: 0 reserved_balance_tc: 0 available_balance_tc: 0 matched_identity: type: example-value status: example-value is_primary: true masked_value: example-value "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE message: The API client lacks the required scope. "404": description: "Errors: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE message: The request cannot be processed with the supplied values. "409": description: "Errors: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: INVALID_IDENTITY_STATUS" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_IDENTITY_STATUS error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_IDENTITY_STATUS message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: customers:read x-error-codes: - INVALID_REQUEST - RESOURCE_NOT_FOUND - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - IDEMPOTENCY_CONFLICT - IDENTITY_CONFLICT - INVALID_IDENTITY_STATUS - RATE_LIMITED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - END_USER_ACCESS_UNAVAILABLE x-idempotency-policy: not-applicable x-rate-limit-class: READ x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. /v1/accounts/{account_id}: get: operationId: account_read tags: - Accounts summary: Read an ownership-authorized credit-account summary. description: Requires API-key authentication and scope `accounts:read`. security: - apiKey: [] parameters: - name: account_id in: path required: true schema: type: string example: acct_test_example_01 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/AccountResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: customer_id: cust_test_example_01 account_id: acct_test_example_01 account_reference: acct_test_01J8Q4M2K7 customer_status: ACTIVE account_status: ACTIVE current_balance_tc: 0 reserved_balance_tc: 0 available_balance_tc: 0 "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE message: The API client lacks the required scope. "404": description: "Errors: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE message: The request cannot be processed with the supplied values. "409": description: "Errors: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: INVALID_IDENTITY_STATUS" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_IDENTITY_STATUS error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_IDENTITY_STATUS message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: accounts:read x-error-codes: - RESOURCE_NOT_FOUND - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - IDENTITY_CONFLICT - INVALID_IDENTITY_STATUS - RATE_LIMITED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - END_USER_ACCESS_UNAVAILABLE x-idempotency-policy: not-applicable x-rate-limit-class: READ x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. /v1/transactions/{transaction_reference}: get: operationId: transaction_read tags: - Transactions summary: Read one ownership-authorized transaction by its external reference. description: Requires API-key authentication and scope `financial:read`. security: - apiKey: [] parameters: - name: transaction_reference in: path required: true schema: type: string example: txn_pub_test_01J8Q4N5R6 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/TransactionResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE message: The API client lacks the required scope. "404": description: "Errors: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND, END_USER_ACCESS_UNAVAILABLE message: The request cannot be processed with the supplied values. "409": description: "Errors: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, IDENTITY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: INVALID_IDENTITY_STATUS" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_IDENTITY_STATUS error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_IDENTITY_STATUS message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: financial:read x-error-codes: - RESOURCE_NOT_FOUND - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - IDENTITY_CONFLICT - INVALID_IDENTITY_STATUS - RATE_LIMITED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - END_USER_ACCESS_UNAVAILABLE x-idempotency-policy: not-applicable x-rate-limit-class: READ x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. /v1/credits: post: operationId: credit_create tags: - Transactions summary: Create an idempotent credit or reward issuance operation. description: Requires API-key authentication and scope `financial:write`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED, REWARD_NOT_AUTHORIZED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED, REWARD_NOT_AUTHORIZED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED, REWARD_NOT_AUTHORIZED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND, REWARD_PROGRAM_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND, REWARD_PROGRAM_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND, REWARD_PROGRAM_NOT_FOUND message: The request cannot be processed with the supplied values. "409": description: "Errors: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE, REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE, REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE, REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON, REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON, REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON, REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: financial:write x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - INSUFFICIENT_AVAILABLE_CREDIT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - INVALID_AMOUNT - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - REWARD_PROGRAM_NOT_FOUND - REWARD_PROGRAM_INACTIVE - REWARD_NOT_AUTHORIZED - REWARD_REFERENCE_CONFLICT - REWARD_LIMIT_EXCEEDED - REWARD_RULE_INVALID - REWARD_TYPE_REASON_MISMATCH - REWARD_AMOUNT_INVALID - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreditRequest" /v1/debits: post: operationId: debit_create tags: - Transactions summary: Create an idempotent debit operation. description: Requires API-key authentication and scope `financial:write`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_AVAILABLE_CREDIT, INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: financial:write x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - INSUFFICIENT_AVAILABLE_CREDIT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - INVALID_AMOUNT - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DebitRequest" /v1/reversals: post: operationId: reversal_create tags: - Transactions summary: Create an idempotent reversal for a previous transaction. description: Requires API-key authentication and scope `credits:reverse`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReversalResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReversalResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_AMOUNT, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: credits:reverse x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - INVALID_AMOUNT - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ACCOUNT_BALANCE_LIMIT_EXCEEDED - INSUFFICIENT_AVAILABLE_CREDIT - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReversalRequest" /v1/reservations: post: operationId: reservation_create tags: - Reservations summary: Reserve available credit for an order. description: Requires API-key authentication and scope `reservations:create`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reservations:create x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - RESERVATION_ORDER_CONFLICT - INSUFFICIENT_AVAILABLE_CREDIT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESERVATION_INSUFFICIENT_AVAILABLE - RESERVATION_EXPIRED - RESERVATION_NOT_MUTABLE - RESERVATION_ACCOUNT_STATE_BLOCKED - RESERVATION_IDEMPOTENCY_CONFLICT - RESERVATION_TTL_OUT_OF_RANGE - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ORDER_ZERO_AMOUNT - INVALID_AMOUNT - ACCOUNT_BALANCE_LIMIT_EXCEEDED - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReservationCreateRequest" /v1/reservations/{reservation_id}: get: operationId: reservation_read tags: - Reservations summary: Read an ownership-authorized reservation. description: Requires API-key authentication and scope `reservations:read`. security: - apiKey: [] parameters: - name: reservation_id in: path required: true schema: type: string responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ORDER_CONFLICT, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, IDEMPOTENCY_CONFLICT, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ORDER_CONFLICT, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, IDEMPOTENCY_CONFLICT, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ORDER_CONFLICT, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, IDEMPOTENCY_CONFLICT, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reservations:read x-error-codes: - RESOURCE_NOT_FOUND - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESERVATION_INSUFFICIENT_AVAILABLE - RESERVATION_EXPIRED - RESERVATION_NOT_MUTABLE - RESERVATION_ORDER_CONFLICT - RESERVATION_ACCOUNT_STATE_BLOCKED - RESERVATION_IDEMPOTENCY_CONFLICT - RESERVATION_TTL_OUT_OF_RANGE - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ORDER_ZERO_AMOUNT - INVALID_AMOUNT - ACCOUNT_BALANCE_LIMIT_EXCEEDED - INSUFFICIENT_AVAILABLE_CREDIT - UNKNOWN_REASON - IDEMPOTENCY_CONFLICT - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: not-applicable x-rate-limit-class: READ x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. /v1/reservations/{reservation_id}/capture: post: operationId: reservation_capture tags: - Reservations summary: Capture part or all of a reservation. description: Requires API-key authentication and scope `reservations:capture`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: reservation_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/FinancialOperationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: transaction_id: txn_test_example_01 public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 operation: DEBIT amount_tc: "1250" current_balance_tc: example-value available_balance_tc: example-value account_sequence: 0 original_transaction_id: txn_test_01J8Q4N5R6 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_AVAILABLE_CREDIT, RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reservations:capture x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - RESERVATION_ORDER_CONFLICT - INSUFFICIENT_AVAILABLE_CREDIT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESERVATION_INSUFFICIENT_AVAILABLE - RESERVATION_EXPIRED - RESERVATION_NOT_MUTABLE - RESERVATION_ACCOUNT_STATE_BLOCKED - RESERVATION_IDEMPOTENCY_CONFLICT - RESERVATION_TTL_OUT_OF_RANGE - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ORDER_ZERO_AMOUNT - INVALID_AMOUNT - ACCOUNT_BALANCE_LIMIT_EXCEEDED - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReservationCaptureRequest" /v1/reservations/{reservation_id}/release: post: operationId: reservation_release tags: - Reservations summary: Release part or all of a reservation. description: Requires API-key authentication and scope `reservations:release`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: reservation_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reservations:release x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - RESERVATION_ORDER_CONFLICT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESERVATION_INSUFFICIENT_AVAILABLE - RESERVATION_EXPIRED - RESERVATION_NOT_MUTABLE - RESERVATION_ACCOUNT_STATE_BLOCKED - RESERVATION_IDEMPOTENCY_CONFLICT - RESERVATION_TTL_OUT_OF_RANGE - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ORDER_ZERO_AMOUNT - INVALID_AMOUNT - ACCOUNT_BALANCE_LIMIT_EXCEEDED - INSUFFICIENT_AVAILABLE_CREDIT - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReservationReleaseRequest" /v1/reservations/{reservation_id}/extend: post: operationId: reservation_extend tags: - Reservations summary: Extend a reservation expiry within the allowed lifetime. description: Requires API-key authentication and scope `reservations:extend`. Idempotency-Key is required. security: - apiKey: [] parameters: - name: reservation_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 example: order-8742-credit-attempt-1 responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "201": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/ReservationResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: reservation_id: example-value public_reference: txn_pub_test_01J8Q4N5R6 account_id: acct_test_example_01 source_system: commerce-platform order_id: order-8742 original_amount_tc: example-value remaining_amount_tc: example-value captured_amount_tc: example-value released_amount_tc: example-value status: ACTIVE created_at: 2026-08-04T10:30:00Z expires_at: 2026-08-04T11:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, LIFECYCLE_TRANSITION_NOT_ALLOWED message: The request cannot be processed with the supplied values. "404": description: "Errors: RESOURCE_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESOURCE_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: RESOURCE_NOT_FOUND message: Resource not found. "409": description: "Errors: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE error envelope value: success: false request_id: req_test_example_01 error: code: IDEMPOTENCY_CONFLICT, RESERVATION_ORDER_CONFLICT, RESERVATION_EXPIRED, RESERVATION_NOT_MUTABLE, RESERVATION_ACCOUNT_STATE_BLOCKED, RESERVATION_IDEMPOTENCY_CONFLICT, ACCOUNT_BALANCE_LIMIT_EXCEEDED, REVERSAL_LIMIT_EXCEEDED, ACCOUNT_FROZEN_DEBIT_BLOCKED, ACCOUNT_CLOSED, LIFECYCLE_GUARD_UNAVAILABLE, RECONCILIATION_HOLD_ACTIVE message: The request cannot be processed with the supplied values. "422": description: "Errors: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON error envelope value: success: false request_id: req_test_example_01 error: code: RESERVATION_INSUFFICIENT_AVAILABLE, RESERVATION_TTL_OUT_OF_RANGE, AMOUNT_MISMATCH, ORDER_ITEM_INVALID, ORDER_ALLOCATION_MISMATCH, ORDER_ALLOCATION_EXCEEDED, ORDER_ZERO_AMOUNT, INVALID_AMOUNT, INSUFFICIENT_AVAILABLE_CREDIT, UNKNOWN_REASON message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reservations:extend x-error-codes: - INVALID_REQUEST - IDEMPOTENCY_CONFLICT - RESOURCE_NOT_FOUND - RESERVATION_ORDER_CONFLICT - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - RESERVATION_INSUFFICIENT_AVAILABLE - RESERVATION_EXPIRED - RESERVATION_NOT_MUTABLE - RESERVATION_ACCOUNT_STATE_BLOCKED - RESERVATION_IDEMPOTENCY_CONFLICT - RESERVATION_TTL_OUT_OF_RANGE - AMOUNT_MISMATCH - ORDER_ITEM_INVALID - ORDER_ALLOCATION_MISMATCH - ORDER_ALLOCATION_EXCEEDED - ORDER_ZERO_AMOUNT - INVALID_AMOUNT - ACCOUNT_BALANCE_LIMIT_EXCEEDED - INSUFFICIENT_AVAILABLE_CREDIT - UNKNOWN_REASON - REVERSAL_LIMIT_EXCEEDED - ACCOUNT_FROZEN_DEBIT_BLOCKED - ACCOUNT_CLOSED - LIFECYCLE_TRANSITION_NOT_ALLOWED - LIFECYCLE_GUARD_UNAVAILABLE - RECONCILIATION_HOLD_ACTIVE - RATE_LIMITED x-idempotency-policy: required x-rate-limit-class: MUTATION x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReservationExtendRequest" /v1/reward-programs/{program_id}: get: operationId: reward_program_read tags: - Rewards summary: Read an ownership-authorized reward program view. description: Requires API-key authentication and scope `reward_programs:read`. security: - apiKey: [] parameters: - name: program_id in: path required: true schema: type: string example: reward-program-summer-2026 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 50 example: 20 - name: before in: query required: false schema: type: string example: cursor_eyJvZmZzZXQiOjIw responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true request_id: type: string data: $ref: "#/components/schemas/RewardProgramResponse" examples: success: summary: Successful response value: success: true request_id: req_test_example_01 data: program_id: reward-program-summer-2026 program_type: CAMPAIGN_REWARD effective_state: example-value ends_at: 2026-12-31T23:59:59Z net_issued_tc: example-value rewards: - reward_reference: reward-8742 amount_tc: "1250" eligibility_reference: eligibility-8742 created_at: 2026-08-04T10:30:00Z "400": description: "Errors: INVALID_REQUEST" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INVALID_REQUEST error envelope value: success: false request_id: req_test_example_01 error: code: INVALID_REQUEST message: The request is invalid. "401": description: "Errors: UNAUTHORIZED, INVALID_API_KEY" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: UNAUTHORIZED, INVALID_API_KEY error envelope value: success: false request_id: req_test_example_01 error: code: UNAUTHORIZED, INVALID_API_KEY message: The request cannot be processed with the supplied values. "403": description: "Errors: INSUFFICIENT_SCOPE, REWARD_NOT_AUTHORIZED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: INSUFFICIENT_SCOPE, REWARD_NOT_AUTHORIZED error envelope value: success: false request_id: req_test_example_01 error: code: INSUFFICIENT_SCOPE, REWARD_NOT_AUTHORIZED message: The request cannot be processed with the supplied values. "404": description: "Errors: REWARD_PROGRAM_NOT_FOUND" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: REWARD_PROGRAM_NOT_FOUND error envelope value: success: false request_id: req_test_example_01 error: code: REWARD_PROGRAM_NOT_FOUND message: Resource not found. "409": description: "Errors: REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED error envelope value: success: false request_id: req_test_example_01 error: code: REWARD_PROGRAM_INACTIVE, REWARD_REFERENCE_CONFLICT, REWARD_LIMIT_EXCEEDED message: The request cannot be processed with the supplied values. "422": description: "Errors: REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID error envelope value: success: false request_id: req_test_example_01 error: code: REWARD_RULE_INVALID, REWARD_TYPE_REASON_MISMATCH, REWARD_AMOUNT_INVALID message: The request cannot be processed with the supplied values. "429": description: "Errors: RATE_LIMITED" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: RATE_LIMITED error envelope value: success: false request_id: req_test_example_01 error: code: RATE_LIMITED message: Too many requests. Retry later. headers: Retry-After: schema: type: integer example: 60 description: Seconds to wait before retrying. "503": description: "Errors: SERVICE_UNAVAILABLE" content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" examples: error: summary: SERVICE_UNAVAILABLE error envelope value: success: false request_id: req_test_example_01 error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. x-required-scope: reward_programs:read x-error-codes: - REWARD_PROGRAM_NOT_FOUND - INVALID_REQUEST - UNAUTHORIZED - INSUFFICIENT_SCOPE - SERVICE_UNAVAILABLE - INVALID_API_KEY - REWARD_PROGRAM_INACTIVE - REWARD_NOT_AUTHORIZED - REWARD_REFERENCE_CONFLICT - REWARD_LIMIT_EXCEEDED - REWARD_RULE_INVALID - REWARD_TYPE_REASON_MISMATCH - REWARD_AMOUNT_INVALID - RATE_LIMITED x-idempotency-policy: not-applicable x-rate-limit-class: READ x-unknown-fields-policy: Do not depend on unknown-field acceptance; only documented fields are supported. x-pagination: style: cursor-before limit_parameter: limit cursor_parameter: before response_cursor: next_before default_limit: 50 maximum_limit: 50 ordering: - created_at DESC - id DESC terminal_cursor: null components: securitySchemes: apiKey: type: http scheme: Bearer bearerFormat: ThalesCreditApiKey description: Environment-specific API key. Never send a Test key to Production or commit a key. schemas: Error: type: object additionalProperties: false required: - code - message properties: code: type: string description: Stable machine-readable error code. message: type: string description: Safe human-readable message. ErrorEnvelope: type: object additionalProperties: false required: - success - request_id - error properties: success: const: false description: Documented success field. request_id: type: string description: Correlation identifier returned by the API. example: req_test_example_01 error: $ref: "#/components/schemas/Error" description: Documented error field. SuccessEnvelope: type: object additionalProperties: false required: - success - request_id - data properties: success: const: true description: Documented success field. request_id: type: string description: Documented request_id field. data: type: object additionalProperties: false description: Documented data field. CustomerCreateRequest: type: object additionalProperties: false required: - identities properties: display_name: type: string maxLength: 200 example: Example Customer locale: type: string maxLength: 35 example: en-GB timezone: type: string maxLength: 64 example: Europe/Berlin identities: type: array minItems: 1 maxItems: 10 items: type: object additionalProperties: false required: - type - value - status properties: type: type: string enum: - XT_UID - TELEGRAM_ID - EMAIL - WEBSITE_USER_ID - CRM_ID example: XT_UID description: External identity namespace. XT_UID is the primary identity type. value: type: string example: "1000123456" description: Documented value field. status: type: string enum: - UNVERIFIED - VERIFIED example: VERIFIED description: Verification state requested for this identity. is_primary: type: boolean description: Documented identities field. CustomerAccountSummary: type: object additionalProperties: false required: - customer_id - account_id - account_reference - customer_status - account_status - current_balance_tc - reserved_balance_tc - available_balance_tc properties: customer_id: type: string example: cust_test_example_01 description: Documented customer_id field. account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 account_reference: type: string example: acct_test_01J8Q4M2K7 description: Documented account_reference field. customer_status: type: string enum: - ACTIVE - PENDING_IDENTITY - MERGED - ANONYMIZED example: ACTIVE description: Customer lifecycle status returned by the API. account_status: type: string enum: - ACTIVE - FROZEN - CLOSED example: ACTIVE description: Credit-account lifecycle status returned by the API. current_balance_tc: type: number description: Documented current_balance_tc field. reserved_balance_tc: type: number description: Documented reserved_balance_tc field. available_balance_tc: type: number description: Documented available_balance_tc field. CustomerCreateResponse: type: object additionalProperties: false required: - customer_id - account_id - account_reference - customer_status - account_status - current_balance_tc - reserved_balance_tc - available_balance_tc - created_at properties: customer_id: type: string example: cust_test_example_01 description: Documented customer_id field. account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 account_reference: type: string example: acct_test_01J8Q4M2K7 description: Documented account_reference field. customer_status: type: string enum: - ACTIVE - PENDING_IDENTITY - MERGED - ANONYMIZED example: ACTIVE description: Customer lifecycle status returned by the API. account_status: type: string enum: - ACTIVE - FROZEN - CLOSED example: ACTIVE description: Credit-account lifecycle status returned by the API. current_balance_tc: type: number description: Documented current_balance_tc field. reserved_balance_tc: type: number description: Documented reserved_balance_tc field. available_balance_tc: type: number description: Documented available_balance_tc field. created_at: type: string format: date-time example: 2026-08-04T10:30:00Z description: Documented created_at field. CustomerLookupQuery: type: object required: - type - value properties: type: type: string enum: - XT_UID - TELEGRAM_ID - EMAIL - WEBSITE_USER_ID - CRM_ID example: XT_UID description: External identity namespace used for exact lookup. value: type: string example: "1000123456" description: Documented value field. CustomerLookupResponse: type: object additionalProperties: false required: - customer_id - account_id - account_reference - customer_status - account_status - current_balance_tc - reserved_balance_tc - available_balance_tc - matched_identity properties: customer_id: type: string example: cust_test_example_01 description: Documented customer_id field. account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 account_reference: type: string example: acct_test_01J8Q4M2K7 description: Documented account_reference field. customer_status: type: string enum: - ACTIVE - PENDING_IDENTITY - MERGED - ANONYMIZED example: ACTIVE description: Customer lifecycle status returned by the API. account_status: type: string enum: - ACTIVE - FROZEN - CLOSED example: ACTIVE description: Credit-account lifecycle status returned by the API. current_balance_tc: type: number description: Documented current_balance_tc field. reserved_balance_tc: type: number description: Documented reserved_balance_tc field. available_balance_tc: type: number description: Documented available_balance_tc field. matched_identity: type: object additionalProperties: false required: - type - status - is_primary - masked_value properties: type: type: string description: Documented type field. status: type: string description: Documented status field. is_primary: type: boolean description: Documented is_primary field. masked_value: type: string description: Documented masked_value field. description: Documented matched_identity field. AccountPath: type: object properties: account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 AccountResponse: $ref: "#/components/schemas/CustomerAccountSummary" TransactionPath: type: object properties: transaction_reference: type: string description: External lookup parameter for a transaction. Use the server-returned public reference; do not construct or derive it from transaction_id. example: txn_pub_test_01J8Q4N5R6 TransactionResponse: type: object additionalProperties: false required: - transaction_id - account_id - operation - amount_tc - current_balance_tc - available_balance_tc - account_sequence properties: transaction_id: type: string description: Server-issued internal transaction identifier returned for correlation. Clients must not construct it; use the returned public_reference for external lookup where available. example: txn_test_example_01 public_reference: type: string description: Server-issued public reference returned in a response. Treat it as opaque and persist it exactly as returned. example: txn_pub_test_01J8Q4N5R6 account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 operation: type: string enum: - CREDIT - DEBIT - DEBIT_REVERSAL example: DEBIT description: Financial operation represented by this transaction. amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" current_balance_tc: type: string description: Documented current_balance_tc field. available_balance_tc: type: string description: Documented available_balance_tc field. account_sequence: type: integer description: Documented account_sequence field. reversal_status: type: string original_transaction_id: type: string description: Server-returned identifier of the transaction being reversed. Copy it from a prior API response; never construct it. example: txn_test_01J8Q4N5R6 created_at: type: string format: date-time example: 2026-08-04T10:30:00Z CreditRequest: type: object additionalProperties: false required: - account_id - amount_tc - reason_code - source_system - external_reference properties: account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 amount_tc: type: string pattern: ^[1-9][0-9]*$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" reason_code: type: string description: Client or account configuration-defined business reason. Use a value enabled for the requested operation; PRODUCT_PURCHASE is an example, not a universal enum. example: PRODUCT_PURCHASE source_system: type: string description: Stable name of the client system submitting the event, used for idempotency and reconciliation. The client owns the value; it is not an API enum. example: commerce-platform external_reference: type: string description: Stable identifier from the integrating system, used for reconciliation and audit. The client owns its format and must not reuse it for a different business event. example: order-8742 reward: type: object additionalProperties: false required: - program_id - customer_id - reward_reference - rule_version_id properties: program_id: type: string example: reward-program-summer-2026 description: Documented program_id field. customer_id: type: string example: cust_test_example_01 description: Documented customer_id field. reward_reference: type: string example: reward-8742 description: Documented reward_reference field. eligibility_reference: type: string example: eligibility-8742 source_event_reference: type: string example: commerce-event-8742 reward_period: type: string example: 2026-08 calculation_reference: type: string example: calc-2026-09-8742 source_metric_summary: type: string example: monthly_purchase_total_tc=12500 rule_version_id: type: string example: rule-v3 description: Documented rule_version_id field. DebitRequest: type: object additionalProperties: false required: - account_id - amount_tc - reason_code - source_system - external_reference properties: account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 amount_tc: type: string pattern: ^[1-9][0-9]*$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" reason_code: type: string description: Client or account configuration-defined business reason. Use a value enabled for the requested operation; PRODUCT_PURCHASE is an example, not a universal enum. example: PRODUCT_PURCHASE source_system: type: string description: Stable name of the client system submitting the event, used for idempotency and reconciliation. The client owns the value; it is not an API enum. example: commerce-platform external_reference: type: string description: Stable identifier from the integrating system, used for reconciliation and audit. The client owns its format and must not reuse it for a different business event. example: order-8742 FinancialOperationResponse: $ref: "#/components/schemas/TransactionResponse" ReversalRequest: type: object additionalProperties: false required: - original_transaction_id - amount_tc - source_system - external_reference properties: original_transaction_id: type: string description: Server-returned identifier of the transaction being reversed. Copy it from a prior API response; never construct it. example: txn_test_01J8Q4N5R6 amount_tc: type: string pattern: ^[1-9][0-9]*$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" source_system: type: string description: Stable name of the client system submitting the event, used for idempotency and reconciliation. The client owns the value; it is not an API enum. example: commerce-platform external_reference: type: string description: Stable identifier from the integrating system, used for reconciliation and audit. The client owns its format and must not reuse it for a different business event. example: order-8742 ReversalResponse: $ref: "#/components/schemas/TransactionResponse" ReservationCreateRequest: type: object additionalProperties: false required: - account_id - amount_tc - source_system - order_id properties: account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 amount_tc: type: string pattern: ^(?:0|[1-9][0-9]*)$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" source_system: type: string description: Stable name of the client system submitting the event, used for idempotency and reconciliation. The client owns the value; it is not an API enum. example: commerce-platform order_id: type: string example: order-8742 description: Documented order_id field. ttl_seconds: type: integer minimum: 60 maximum: 86400 example: 3600 cancellation_reference: type: string example: cancel-order-8742 line_items: type: array items: type: object additionalProperties: false required: - item_id - item_type - amount_tc properties: item_id: type: string maxLength: 128 example: product-8742-1 description: Documented item_id field. item_type: type: string enum: - PRODUCT - SERVICE - DISCOUNT example: PRODUCT description: Documented item_type field. amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" metadata: type: object additionalProperties: type: - string - number ReservationPath: type: object properties: reservation_id: type: string description: Server-issued reservation identifier returned by reservation creation. Persist and reuse it; never construct it. ReservationResponse: type: object additionalProperties: false required: - reservation_id - status - original_amount_tc - remaining_amount_tc - captured_amount_tc - released_amount_tc - expires_at properties: reservation_id: type: string description: Server-issued reservation identifier returned by reservation creation. Persist and reuse it; never construct it. reservation_reference: type: string description: Server-issued public reservation reference. Treat it as opaque and persist it exactly as returned. public_reference: type: string description: Server-issued public reference returned in a response. Treat it as opaque and persist it exactly as returned. example: txn_pub_test_01J8Q4N5R6 account_id: type: string description: Server-issued account identifier returned by the API. Persist and reuse it; never construct internal identifiers. example: acct_test_example_01 source_system: type: string description: Stable name of the client system submitting the event, used for idempotency and reconciliation. The client owns the value; it is not an API enum. example: commerce-platform order_id: type: string example: order-8742 original_amount_tc: type: string description: Documented original_amount_tc field. remaining_amount_tc: type: string description: Documented remaining_amount_tc field. captured_amount_tc: type: string description: Documented captured_amount_tc field. released_amount_tc: type: string description: Documented released_amount_tc field. status: type: string enum: - ACTIVE - PARTIALLY_CAPTURED - PARTIALLY_RELEASED - COMPLETED - RELEASED - EXPIRED example: ACTIVE description: Reservation lifecycle state returned by the API. created_at: type: string format: date-time example: 2026-08-04T10:30:00Z updated_at: type: string format: date-time expires_at: type: string format: date-time example: 2026-08-04T11:30:00Z description: Documented expires_at field. current_balance_tc: type: string reserved_balance_tc: type: string available_balance_tc: type: string account_sequence: type: integer order_snapshot: type: object additionalProperties: false properties: order_id: type: string example: order-8742 orderId: type: string api_version: type: string apiVersion: type: string schema_version: type: string schemaVersion: type: string total_amount_tc: type: string totalAmountTc: type: string metadata_json: type: string example: '{"channel":"web"}' created_at: type: string format: date-time example: 2026-08-04T10:30:00Z line_items: type: array items: type: object additionalProperties: false properties: item_id: type: string example: product-8742-1 itemId: type: string item_type: type: string itemType: type: string amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" amountTc: type: string metadata_json: type: string example: '{"channel":"web"}' metadata: type: object additionalProperties: type: - string - number ReservationCaptureRequest: type: object additionalProperties: false required: - amount_tc - reason_code properties: amount_tc: type: string pattern: ^[1-9][0-9]*$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" reason_code: type: string enum: - PRODUCT_PURCHASE - SERVICE_PURCHASE example: PRODUCT_PURCHASE description: Client or account configuration-defined business reason. Use a value enabled for the requested operation; PRODUCT_PURCHASE is an example, not a universal enum. cancellation_reference: type: string example: cancel-order-8742 allocations: type: array items: type: object additionalProperties: false required: - item_id - amount_tc properties: item_id: type: string maxLength: 128 example: product-8742-1 description: Documented item_id field. amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" ReservationReleaseRequest: type: object additionalProperties: false required: - amount_tc properties: amount_tc: type: string pattern: ^[1-9][0-9]*$ description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" cancellation_reference: type: string example: cancel-order-8742 allocations: type: array items: type: object additionalProperties: false required: - item_id - amount_tc properties: item_id: type: string maxLength: 128 example: product-8742-1 description: Documented item_id field. amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" ReservationExtendRequest: type: object additionalProperties: false required: - ttl_seconds properties: ttl_seconds: type: integer minimum: 60 maximum: 86400 example: 3600 description: Documented ttl_seconds field. RewardProgramQuery: type: object additionalProperties: false properties: program_id: type: string example: reward-program-summer-2026 limit: type: integer minimum: 1 maximum: 50 example: 20 before: type: string example: cursor_eyJvZmZzZXQiOjIw RewardProgramResponse: type: object additionalProperties: false required: - program_id - program_type - effective_state - net_issued_tc - rewards properties: program_id: type: string example: reward-program-summer-2026 description: Documented program_id field. program_type: type: string enum: - TRADING_REWARD - CAMPAIGN_REWARD - MANUAL_BONUS - ADMIN_ADJUSTMENT - INITIAL_IMPORT example: CAMPAIGN_REWARD description: Closed set of reward program types exposed by the API. effective_state: type: string description: Documented effective_state field. starts_at: type: - string - "null" format: date-time ends_at: type: - string - "null" format: date-time example: 2026-12-31T23:59:59Z net_issued_tc: type: string description: Documented net_issued_tc field. rewards: type: array items: type: object additionalProperties: false required: - reward_reference - amount_tc - eligibility_reference - created_at properties: reward_reference: type: string example: reward-8742 description: Documented reward_reference field. amount_tc: type: string description: String-encoded whole-number amount in TC units. No decimal or fractional values are accepted. Financial mutations and reservation transitions require a positive amount; reservation creation has separate order validation. The implementation rejects values above its safe integer boundary and enforces the applicable account credit limit. example: "1250" eligibility_reference: type: string example: eligibility-8742 description: Documented eligibility_reference field. created_at: type: string format: date-time example: 2026-08-04T10:30:00Z description: Documented created_at field. description: Documented rewards field. next_before: type: - string - "null" externalDocs: description: External integration guide url: ./guide.html