Thales Credit Core External API

This is the official external server-to-server integration guide for Thales Credit Core V1.

The machine-readable contract is available as the OpenAPI 3.1 specification. Endpoint schemas, parameters, status codes, and reusable models must be read from that generated artifact.

Canonical contract

The external API is versioned under /v1 and is intended for trusted backend integrations. API keys must never be exposed in browser code, mobile binaries, HTML, logs, or source control.

Supported V1 operations

• Customer creation and exact identity lookup
• Account summary read
• Transaction read by external reference
• Credit and debit operations, including governed reward issuance through POST /v1/credits
• Reversal operations
• Reservation create/read/capture/release/extend
• Reward program read

Reward issuance

Reward issuance requires financial:write, rewards:issue, and the specific active reason code granted to the Test client. The reward program must be active, owned by the authenticated client, and have an active rule version.

curl --request POST \
  --url 'https://thales-credit-core-test.hamed-saffarian.workers.dev/v1/credits' \
  --header 'Authorization: Bearer <test-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: reward-test-0001' \
  --data '{
    "account_id": "<ACCOUNT_ID>",
    "amount_tc": "100",
    "reason_code": "<GRANTED_REASON_CODE>",
    "source_system": "synthetic-rewards",
    "external_reference": "reward-test-0001",
    "reward": {
      "program_id": "<REWARD_PROGRAM_ID>",
      "program_type": "TRADING_REWARD",
      "customer_id": "<CUSTOMER_ID>",
      "reward_reference": "reward-test-0001",
      "rule_version_id": "<RULE_VERSION_ID>"
    }
  }'

Replace <GRANTED_REASON_CODE> with the active reason code explicitly granted to your Test client; do not assume that TRADING_REWARD is available. The external integration supplies the already-approved amount and reward references. Credit Core validates ownership, program state, limits, rule version, idempotency, and reason-code authorization; it does not calculate eligibility or reward amounts. Use synthetic Test identifiers only.

Test-only Webhook receiver contract

Webhooks are outbound notifications delivered to an HTTPS endpoint owned by the integrating service. They are not inbound Credit Core routes and this site does not provision a receiver URL. The V1 event types are credit.created, debit.created, reversal.created, reservation.created, reservation.captured, reservation.released, reservation.expired, account.frozen, account.reopened, and account.closed.

Verify X-Credit-Signature: t=<unix>,v1=<hex> over <timestamp>\n<raw-request-body-bytes> before parsing JSON. Reject timestamps more than 300 seconds (5 minutes) from receiver time, use constant-time comparison, deduplicate by event_id, and retain current plus previous secrets during the 24-hour rotation overlap. Use account_sequence and reservation_sequence for ordering decisions; network order is not guaranteed. Delivery is at-least-once and retries immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours; Admin-only resend preserves the same event ID and payload.

These are synthetic Test examples only. No Production endpoint, credential, internal identifier, or inbound Credit Core webhook route is published. See the integration guide and generated Webhooks reference.

Excluded from this public V1 document

• Admin API and Admin UI
• Embedded end-user credit UI/reference routes
• Test/spike routes
• CSV reward imports
• Health responses exposing environment/version
• Client-info responses containing internal client identity
• Account transaction history until its continuation contract is complete

Environments

Use the Test base URL https://thales-credit-core-test.hamed-saffarian.workers.dev and a Test API key for integration testing. Production is separately governed and is not provisioned or enabled by this documentation publication. Never copy credentials between environments.

Contract support

OpenAPI generation, linting, route-inventory comparison, contract tests, secret scanning, and compatibility checks run in CI. Implementation, inventory, OpenAPI, examples, and tests must remain consistent.

← Back to API reference