Digital Twin · Authorization & settlement
Integration pattern

Card authorization → settlement

For debit-card flows that authorize now and settle later — hotel, gas station, restaurant + tip, e-commerce pre-auth — Digital Twin has one recommended pattern. Use it and there is no window where reserved money is briefly spendable.

The one rule. Hold the amount to a held/blocked balance at authorization, then at settlement release that hold combined with posting the actual debit — as a single all-or-nothing operation. Release and debit are the same entry, so the money is never spendable in between (no deposit leak).

1Authorize — place the hold (blocking)

A blocking entry reserves the amount: it moves from available into a held balance. Nothing is posted to the ledger yet; the customer’s available balance drops immediately.

POST /v1/accounts/1/1000123456/batches

{
  "entries": [
    {
      "entryKind": "blocking",
      "status": "ON_HOLD",
      "correlationId": "auth-2026-000777",          // keep this — it is your hold reference
      "holdReasonId": "CARD_AUTH",
      "settlementInfo": { "fulfillment": "TOTAL",
                          "amount": { "value": 15000, "currency": "USD" } }
    }
  ]
}

Effect: available −$150.00, held +$150.00. Amounts are integer minor units ($150.00 → 15000).

2Settle in full — release + post together (unblocking)

A single unblocking entry releases the hold and posts the real debit in one movement. releasing.correlationId points back at the hold from step 1. Submitting it in a same-account batch makes it all-or-nothing.

POST /v1/accounts/1/1000123456/batches

{
  "entries": [
    {
      "entryKind": "unblocking",
      "status": "POSTED",
      "correlationId": "settle-2026-000777",
      "holdReasonId": "CARD_AUTH",
      "releasing": { "correlationId": "auth-2026-000777" },
      "settlementInfo": { "fulfillment": "TOTAL",
                          "amount": { "value": 15000, "currency": "USD" } }
    }
  ]
}

3Settle for less — the hotel / gas case (PARTIAL)

When the final amount is lower than the hold, settle with fulfillment: PARTIAL and an amountRange. The entry settles the real amount and the unsettled remainder of the hold is released automatically. A $150.00 hold finalizing at $120.00:

{
  "entries": [
    {
      "entryKind": "unblocking",
      "status": "POSTED",
      "correlationId": "settle-2026-000777",
      "holdReasonId": "CARD_AUTH",
      "releasing": { "correlationId": "auth-2026-000777" },
      "settlementInfo": { "fulfillment": "PARTIAL",
                          "amountRange": { "min": 12000, "max": 12000, "currency": "USD" } }
    }
  ]
}

Settles $120.00, releases the remaining $30.00 back to available. Multiple captures against one hold are supported — submit successive partial settlements.

Why this pattern — no deposit leak

Release + debit are one entry
There is no intermediate state where the hold is gone but the debit has not landed — it is a single entry with both balance legs.
The batch is all-or-nothing
A same-account batch is one transaction. If settlement fails, the original hold is left untouched — nothing is half-applied.
Together, the reserved amount is never transiently spendable. The hold uses a real held balance (see the ledger model) — a held balance, not a computed one.
← REST APIs Messaging model →