Understand the system before your first request

Quick start

The documentation host only serves these pages. Send API requests to the API host, not to the Pages documentation URL.

Authentication header

Authorization: Bearer <environment-specific-api-key>

First read-only request

Exact customer lookup is read-only and does not create an account. The identity type and value must match an identity already registered for the client’s customer.

curl --request GET \
  --url 'https://thales-credit-core-test.hamed-saffarian.workers.dev/v1/customers/lookup?type=XT_UID&value=1000123456' \
  --header 'Authorization: Bearer <test-api-key>'

Expected success response

{
  "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": 2500,
    "reserved_balance_tc": 300,
    "available_balance_tc": 2200
  }
}

Expected authentication error

HTTP/1.1 401 Unauthorized
{
  "success": false,
  "request_id": "req_test_example_01",
  "error": {"code": "INVALID_API_KEY", "message": "The API key is invalid."}
}

Environments and key separation

Use the Test API host with a Test key and Test data. Production keys and data must never be sent to Test, and Test keys must never be sent to Production. Production publication is blocked until the Production Worker, host, credentials, and governance approval exist.

Authentication and scopes

Every published operation is protected by an environment-specific Bearer API key. Keep the key in a trusted server-side integration; never put it in browser JavaScript, mobile binaries, HTML, logs, or source control.

Authorization: Bearer <environment-specific-api-key>

Authentication and authorization are separate. A valid active key can still receive 403 INSUFFICIENT_SCOPE when its client lacks the operation’s required scope. The exact scope is shown beside every operation in the reference.

The implementation supports key replacement and revocation through controlled administrative operations, but those Admin routes are not part of this public V1 contract. Follow the project owner’s approved key-management process for rotation, expiry, and revocation; this documentation does not expose Admin endpoints.

Identifier glossary

Mental model

A customer owns a credit account. Financial operations change the account’s ledger balance. A reservation temporarily protects available credit for an order; capture finalizes fulfilled value and release returns unused value.

Amounts and balances

amount_tc is a string-encoded whole-number amount in TC units. It is not a decimal amount and has no fractional scaling in the public contract. For example, "1250" means 1,250 TC units.

• Financial credit, debit, reversal, capture, and release amounts must be positive.
• Reservation creation has separate order and line-item validation; zero is only accepted where the reservation order rules permit it.
• Values above the implementation’s safe integer boundary are rejected.
• The account credit limit is 10,000 TC; operations that would exceed applicable limits are rejected.
• Current balance is the ledger balance; reserved balance is protected by active reservations; available balance is current balance minus reserved balance.

Use the returned balance fields. Do not reconstruct them from undocumented data.

Customers and accounts

Create a customer

POST /v1/customers
Authorization: Bearer <test-api-key>
Idempotency-Key: onboarding-customer-10042

{
  "display_name": "Example Customer",
  "locale": "en-GB",
  "timezone": "Europe/Berlin",
  "identities": [
    {"type": "XT_UID", "value": "1000123456", "status": "VERIFIED", "is_primary": true}
  ]
}

The response returns server-issued customer and account identifiers. Save them; do not manufacture replacements.

Read an account

GET /v1/accounts/acct_test_example_01
Authorization: Bearer <test-api-key>

Transactions

Use a credit to add approved value, a debit to consume available value immediately, and a reversal to create a compensating auditable event for a prior transaction.

POST /v1/debits
Authorization: Bearer <test-api-key>
Idempotency-Key: purchase-order-8742

{
  "account_id": "acct_test_example_01",
  "amount_tc": "1250",
  "reason_code": "PRODUCT_PURCHASE",
  "source_system": "commerce-platform",
  "external_reference": "order-8742"
}

reason_code and source_system are configuration/client-defined. The examples are not a universal enum.

Reservation lifecycle

Reservations are for orders whose final fulfilled value is not known at authorization time.

Create

POST /v1/reservations
Authorization: Bearer <test-api-key>
Idempotency-Key: reserve-order-8742

{
  "account_id": "acct_test_example_01",
  "amount_tc": "1000",
  "source_system": "commerce-platform",
  "order_id": "order-8742",
  "ttl_seconds": 3600,
  "line_items": [
    {"item_id": "product-8742-1", "item_type": "PRODUCT", "amount_tc": "1000"}
  ]
}

Full capture

POST /v1/reservations/resv_test_example_01/capture
Authorization: Bearer <test-api-key>
Idempotency-Key: capture-order-8742

{"amount_tc":"1000","reason_code":"PRODUCT_PURCHASE"}

Expected result: status: COMPLETED, remaining_amount_tc: "0", and captured_amount_tc: "1000".

Partial capture

POST /v1/reservations/resv_test_example_01/capture
Idempotency-Key: capture-order-8742-part-1

{"amount_tc":"800","reason_code":"PRODUCT_PURCHASE"}

Expected result: status: PARTIALLY_CAPTURED and remaining_amount_tc: "200".

Release

POST /v1/reservations/resv_test_example_01/release
Idempotency-Key: release-order-8742

{"amount_tc":"200"}

Expected result: status: RELEASED and released_amount_tc: "200".

Read and extend

GET /v1/reservations/resv_test_example_01

POST /v1/reservations/resv_test_example_01/extend
Idempotency-Key: extend-order-8742

{"ttl_seconds":7200}

Extension uses server time and is allowed only for a mutable reservation within the configured lifetime bounds. Capture, release, and extend race with expiry under server-side concurrency control; if expiry wins, the API returns 409 RESERVATION_EXPIRED.

Expired reservation

{
  "success": true,
  "data": {"reservation_id":"resv_test_example_01","status":"EXPIRED","remaining_amount_tc":"0","released_amount_tc":"200"}
}

Invalid lifecycle transition

HTTP/1.1 409 Conflict
{
  "success": false,
  "request_id": "req_test_example_01",
  "error": {"code":"RESERVATION_NOT_MUTABLE","message":"The reservation is not mutable."}
}

Rewards

Reward context is bounded and attached to an approved credit event. Reward programs expose only the public summary. Do not reproduce hidden rules or use Admin/CSV routes from a client integration.

Errors, retries, and reconciliation

Every error uses one stable envelope:

{
  "success": false,
  "request_id": "req_test_example_01",
  "error": {"code":"INSUFFICIENT_AVAILABLE_CREDIT","message":"The account has insufficient available credit."}
}

request_id is for support correlation, not idempotency. The current error contract has no validation-details object; rely on code and message.

Obtaining Test credentials

This repository does not document a public self-service credential endpoint. Request Test access through the project’s approved API-client owner or platform operations process. Do not put a real key in this guide, the repository, browser code, or issue comments.

Public boundary and versioning

This guide covers the 13 approved V1 HTTP operations only. Admin, UI/reference, test-only, CSV, incomplete account-history, and webhook routes are excluded. Webhooks remain proposed/inactive. The generated OpenAPI YAML is the contract source for the API reference.