REST APIs

Digital Twin REST endpoints

Synchronous endpoints, secured by OAuth2 (mTLS at the gateway). Post a transaction, and read balances/statements. The same operations also exist asynchronously over Kafka — see AVRO / Kafka messages.

Amounts are unscaled integers in minor units ($50.00 → 5000; scale follows the currency). An account is identified by branch + account. Response schemas follow the generated OpenAPI.

POST /v1/accounts/{branch}/{account}/batches

Posts a batch of one or more entries against an account. Each entry applies a history code (entryType) to one or more balances atomically. entryKind ∈ ledger | blocking | unblocking | reversal | removal.

Request body

{
  "entries": [
    {
      "entryKind": "ledger",
      "correlationId": "a1f3-9c20-...",
      "description": "POS purchase",
      "entryType": 998,
      "amount": { "value": 5000, "currency": "USD" }
    }
  ]
}

201 Response · EntryBatchGroupResponse

{
  "entries": [
    { "correlationId": "a1f3-9c20-...", "entryType": 998, "status": "POSTED" }
  ]
}

Errors

409correlationId already used with a different payload (idempotent replay).

422Unknown history code, a rule declined the entry (RFC-7807 Problem), or insufficient funds.

403Partner scope does not permit this domain.

GET /v1/accounts/{branch}/{account}/balances

Reads an account's balances (one asset) in real time. Served by the Balance & Statements service (read model fed from transaction events).

{
  "branch": 1,
  "account": 928013,
  "balances": [
    { "type": "AVAILABLE", "value": 482010, "currency": "USD" },
    { "type": "HELD",      "value": 30000,  "currency": "USD" }
  ]
}

DELETE /v1/accounts/{branch}/{account}/entries?correlationId=…

Removes a pending entry by its correlationId (before it settles). Posted entries are immutable — to undo a posted one, post a reversal (below). Returns 204 No Content.

GET /v1/entries

Lists the immutable journal of entries (statement), served by the Balance & Statements service. Filter by account and date window; v2 offers richer filters.

Query parameters

branch, accounttarget account

from, todate window (ISO-8601)

{
  "entries": [
    { "correlationId": "a1f3-9c20-...", "entryType": 998,
      "amount": { "value": 5000, "currency": "USD" },
      "status": "POSTED", "asOfDate": "2026-06-21" }
  ]
}

POST /v1/accounts/{branch}/{account}/batches · reversal

Reverses a posted entry by posting a reversal entry (entryKind: reversal) that references the original correlationId. The journal stays immutable — a new compensating entry is created.

{
  "entries": [
    {
      "entryKind": "reversal",
      "correlationId": "b7d1-44a2-...",
      "reverses": "a1f3-9c20-..."
    }
  ]
}

Multi-account? Use POST /v1/transaction-bundles (Composite Transaction service) to move value across several accounts atomically.

← Security & access AVRO / Kafka messages →