# Digital Twin — Card Authorization

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 →