> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization and settlement: every scenario
> Mapped to the nine Auth scenarios.
## Authorization and settlement: every scenario
Whether your cardholder is paying an online merchant, withdrawing cash at an ATM or returning goods for a refund, DCS splits every movement of funds into two clean stages for you: the **authorization stage** places or releases a hold, and the **settlement stage** performs the real debit or refund. This page lists every combination of the two so that you can map each business situation to your own books during integration. DCS is a licensed issuer and its own BIN sponsor: holds and debits are executed by DCS on the card network side, while the authorization decision stays with the partner.
> Before reading on, it helps to know how three entities relate to each other. An **authorization** records the decision to hold or release funds, an **Outstanding** tracks how much is currently held as amounts accumulate and are drawn down, and a **transaction** records the debit or refund that actually happened. See [Authorization](./authorization) and [Transaction records](./transaction).
***
## Mental model: Auth, Outstanding, Transaction
* Once an authorization is approved, DCS places the hold and creates (or reuses) an **Outstanding**, whose `amount` carries the total currently held.
* Later authorizations such as incremental authorizations and reversals use `originalAuthId` to find the `outsId` of the first authorization, then add to or subtract from the **same Outstanding**.
* When settlement arrives, DCS draws the Outstanding down to zero and creates a transaction record. If the settled amount differs from the amount held, DCS automatically back-fills a **FORCE\_AUTH** authorization to top up or release the difference.
> **Key fields**: `authId` (authorization ID), `outsId` (bill or Outstanding ID, the link between authorization and settlement), `originalAuthId` (the authorization being referenced), `direction` (`OUTGOING` holds, `INCOMING` releases) and `authType` (authorization type). The full field list is in [the authorization data structure](./authorization).
### Authorization type (authType)
| Value | Meaning | Who triggers it |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `NORMAL` | Normal authorization, created from a real-time network callback; covers purchases, incremental authorizations, reversals, refunds, cash withdrawals and enquiries | Card network, in real time |
| `FORCE_AUTH` | Forced authorization, back-filled by DCS: settlement has no matching authorization (an offline transaction), or the settled amount differs from the amount held and needs to be trued up | DCS, automatically |
| `EXPIRED_RELEASE` | Expiry release: the authorization expired before settlement and the network instructed the release through a settlement file | Network settlement file |
| `STATUS_DIFF_RELEASE` | Status mismatch release: the network declined on timeout while DCS had approved, corrected during reconciliation | DCS reconciliation |
***
## Scenario overview
The 13 scenarios below cover every combination of authorization and settlement. The "Outstanding, final" column is 0 throughout, which is what tells you the fund lifecycle has closed.
| # | Scenario | Authorization stage (hold / release) | Settlement stage (debit / refund) | Outstanding, final |
| -- | ------------------------------------------------------------------ | ------------------------------------ | --------------------------------------------------- | -----------------: |
| 1 | Normal authorization, normal settlement | Hold 100 | Debit 100 | 0 |
| 2 | Normal authorization, incremental authorization, normal settlement | Hold 100 plus 20 more | Debit 120 | 0 |
| 3 | Normal authorization, partial reversal, normal settlement | Hold 100 minus release of 30 | Debit 70 | 0 |
| 4 | Normal authorization, full reversal | Hold 100 minus release of 100 | None | 0 |
| 5 | Normal authorization, excess capture | Hold 100 | Debit 150 (the extra 50 held by a FORCE\_AUTH) | 0 |
| 6 | Normal authorization, under capture | Hold 100 | Debit 80 (the surplus 20 released by a FORCE\_AUTH) | 0 |
| 7 | Normal authorization, partial capture, final capture | Hold 100 | Debit 60 plus debit 40 | 0 |
| 8 | Forced capture with no authorization | No hold | Direct debit of 100 | 0 |
| 9 | Forced refund with no authorization | No hold | Direct refund of 50 | 0 |
| 10 | Enquiry authorization | Amount 0, nothing held | None | 0 |
| 11 | Authorization expiry release | Hold 100, then release 100 | None | 0 |
| 12 | Authorization timeout mismatch | Hold 100, then roll back 100 | None | 0 |
| 13 | Cash withdrawal (settlement plus withdrawal fee) | Hold 110, then release 10 | Debit 100 plus fee of 10 | 0 |
> Reading convention: each action sequence is annotated as `direction / authType / outsId(change in amount)`. `A` means approved (`approveFlag=A`) and `D` means declined.
***
## Scenario detail
### Scenario 1: normal authorization, normal settlement
The base case: one hold, one settlement debit, amounts matching exactly.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL, A), `outsId1` (amount=100)
2. Settlement: OUTGOING, debit 100 USD, `transactionId1`, `outsId1` (amount=100→0)
| Step | authorization | outstanding | transaction |
| ---------------------- | --------------------------------- | --------------------- | ------------------------------------- |
| Authorization approved | `authId1`: OUTGOING, A, `outsId1` | `outsId1`: amount=100 | — |
| Settlement completed | — | `outsId1`: amount=0 | `transactionId1`: OUTGOING, `outsId1` |
### Scenario 2: normal authorization, incremental authorization, normal settlement
The merchant holds an additional amount, as a hotel does when adding a gratuity. Several authorizations share one Outstanding.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Authorization: OUTGOING, hold 20 USD, `authId2` (NORMAL), `outsId1` (amount=100→120)
3. Settlement: OUTGOING, debit 120 USD, `transactionId1`, `outsId1` (amount=120→0)
The incremental authorization uses `originalAuthId` to find the `outsId` of the first authorization and adds to the same Outstanding.
### Scenario 3: normal authorization, partial reversal, normal settlement
The cardholder returns part of the purchase, the merchant sends a partial reversal, and settlement follows for the remainder.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Authorization: INCOMING, release 30 USD, `authId2` (NORMAL), `outsId1` (amount=100→70)
3. Settlement: OUTGOING, debit 70 USD, `transactionId1`, `outsId1` (amount=70→0)
### Scenario 4: normal authorization, full reversal
The cardholder cancels, the merchant sends a full reversal, and no settlement follows.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Authorization: INCOMING, release 100 USD, `authId2` (NORMAL), `outsId1` (amount=100→0)
Once the Outstanding is back to zero, there is nothing left to settle.
### Scenario 5: normal authorization, excess capture
The settled amount is larger than the amount held, because of an exchange-rate move or an added fee. Within the same database transaction, DCS back-fills an OUTGOING `FORCE_AUTH` for the difference.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Settlement processing, in one transaction:
1. Authorization: OUTGOING, hold 50 USD, `authId2` (FORCE\_AUTH), `outsId1` (amount=100→150)
2. Settlement: OUTGOING, debit 150 USD, `transactionId1`, `outsId1` (amount=150→0)
### Scenario 6: normal authorization, under capture
The settled amount is smaller than the amount held. Within the same database transaction, DCS back-fills an INCOMING `FORCE_AUTH` to release the surplus.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Settlement processing, in one transaction:
1. Authorization: INCOMING, release 20 USD, `authId2` (FORCE\_AUTH), `outsId1` (amount=100→80)
2. Settlement: OUTGOING, debit 80 USD, `transactionId1`, `outsId1` (amount=80→0)
### Scenario 7: normal authorization, partial capture, final capture
Multiple captures, identified by the `multiClearInd` field on the transaction record: every capture but the last one only draws the Outstanding down, and the difference is checked on the final one.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. Settlement: OUTGOING, debit 60 USD, `transactionId1` (multiClearInd=P), `outsId1` (amount=100→40)
3. Settlement: OUTGOING, debit 40 USD, `transactionId2` (multiClearInd=F), `outsId1` (amount=40→0)
If a difference remains after the final capture, DCS back-fills a `FORCE_AUTH` following the logic of scenarios 5 and 6.
> `multiClearInd` values: `O` for an ordinary single capture, `P` for a capture that is not the last one, `F` for the capture that completes the set. See [Capture scenarios](./capture-scenarios).
### Scenario 8: forced capture with no authorization
For an offline transaction, settlement arrives with no matching authorization, so DCS back-fills a complete Auth plus Outstanding within the same database transaction.
1. Settlement processing, in one transaction:
1. Authorization: OUTGOING, hold 100 USD, `authId1` (FORCE\_AUTH, A), `outsId1` (amount=0)
2. Settlement: OUTGOING, debit 100 USD, `transactionId1`, `outsId1` (amount=0)
The Outstanding `amount` is set straight to 0, the `FORCE_AUTH` is auto-approved, and all three records are created in the same transaction.
### Scenario 9: forced refund with no authorization
A refund settles with no matching authorization, so DCS creates a new Outstanding purely to keep the records linked.
1. Settlement processing, in one transaction:
1. Settlement: INCOMING, refund 50 USD, `transactionId1`, `outsId1` (amount=0)
Unlike a forced capture, the INCOMING direction does not back-fill an Auth; only the Outstanding is created, for linkage.
### Scenario 10: enquiry authorization
A zero-amount enquiry authorization that only checks whether the card is valid. Nothing is held.
1. Authorization: OUTGOING, hold 0 USD, `authId1` (NORMAL), `outsId1` (amount=0)
An Outstanding is still created (amount=0), but no funds are held. The partner still receives the authorization webhook, with `transactionType=Q`.
### Scenario 11: authorization expiry release
The authorization passed its validity period without settling, and the network instructs the release of the held funds through a settlement file.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. (Validity period passes, no settlement received)
3. Authorization: INCOMING, release 100 USD, `authId2` (EXPIRED\_RELEASE), `outsId1` (amount=100→0)
> The release is applied only if the amount matches the Outstanding **exactly and in the same currency**. A mismatch raises an internal DCS alert and is not processed.
### Scenario 12: authorization timeout mismatch
The network declined the authorization on timeout while DCS may already have approved it, so reconciliation has to correct the difference.
1. Authorization: OUTGOING, hold 100 USD, `authId1` (NORMAL), `outsId1` (amount=100)
2. (Network declined on timeout, DCS had approved, states disagree)
3. Authorization: INCOMING, roll back 100 USD, `authId2` (STATUS\_DIFF\_RELEASE), `outsId1` (amount rolled back)
How it is handled:
* DCS approved (`approveFlag=A`) and the network declined on timeout: a reverse authorization is created (STATUS\_DIFF\_RELEASE, INCOMING) and the Outstanding is rolled back.
* DCS declined (`approveFlag=D`): the states agree, nothing to do.
* No related authorization found: a record is created (STATUS\_DIFF\_RELEASE, `approveFlag=D`) for audit only, with no effect on funds.
### Scenario 13: cash withdrawal (normal settlement plus withdrawal fee)
The authorization stage holds the total of principal and fee. At settlement the fee portion is released first, following the under-capture logic, and the principal is debited; the fee is then debited through its own FORCE\_AUTH and settlement pair.
1. Authorization: OUTGOING, hold 110 USD, `authId1` (NORMAL), `outsId1` (amount=110)
2. Principal settlement processing, in one transaction:
1. Authorization: INCOMING, release 10 USD, `authId2` (FORCE\_AUTH), `outsId1` (amount=110→100)
2. Settlement: OUTGOING, debit 100 USD, `transactionId1` (category=CASH), `outsId1` (amount=100→0)
3. Fee forced-posting settlement processing, in one transaction:
1. Authorization: OUTGOING, hold 10 USD, `authId3` (FORCE\_AUTH), `outsId2` (amount=10)
2. Settlement: OUTGOING, debit 10 USD, `transactionId2` (category=CASH\_FEES), `outsId2` (amount=10→0)
How it is handled:
* The authorization holds 110 USD (100 principal plus 10 fee), and `outsId1` carries the total held.
* Settling the principal, DCS sees that the settled amount (100) is below the Outstanding (110), so under-capture logic back-fills an INCOMING `FORCE_AUTH` releasing the 10 difference before debiting 100.
* The fee goes through forced posting on its own: a new `outsId2` is created, a `FORCE_AUTH` holds 10, and 10 is settled and debited immediately.
> **How do you tell withdrawal principal from fee?** By the `category` field on the transaction record.
>
> The authoritative `category` values are in the [transaction category dictionary](../reports/field-dictionary): withdrawal principal is `CASH` and the withdrawal fee is `CASH_FEES`.
***
## A walkthrough: hotel pre-authorization to posting
Here is scenario 3 (partial reversal) on a real timeline — what you receive at each touchpoint, what you do, and how the books tie out. The case: your cardholder books three hotel nights with a 100 USD pre-authorization, cancels one night after check-in (the hotel reverses 30 USD), and the hotel captures 70 USD after checkout.
| Time | Event | What you receive | What you do | Outstanding `outsId1` |
| ----- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------: |
| Day 1 | Hotel pre-authorizes 100 USD | Real-time request on `authUrl`: `authId1`, `OUTGOING`, `NORMAL`, amount=100 | Decide within 2.5 s, return `00` | 0 → 100 |
| Day 1 | DCS freezes and sends the receipt | `AUTHORISATION_RESULT`: `authId1`, `approveFlag=A` | Book it: 100 frozen for this user | 100 |
| Day 3 | Hotel reverses one night, 30 USD | Real-time request on `authUrl`: `authId2`, `INCOMING`, `NORMAL`, amount=30, `originalAuthId=authId1` | Return `00` | 100 → 70 |
| Day 3 | DCS unfreezes and sends the receipt | `AUTHORISATION_RESULT`: `authId2`, `approveFlag=A` | Book it: frozen amount drops to 70 | 70 |
| Day 4 | The network settles 70 USD | (settlement sends no real-time notification) | — | 70 → 0 |
| Day 5 | Reconciliation files are generated | Two rows in the authorization report (`authId1`/`authId2`, same `outsId1`) + one row in the transaction report (`transactionId1`, 70 debited) | Tie out by `outsId1`: frozen 100 − released 30 = settled 70, closed | 0 |
Three reconciliation take-aways:
* **`outsId1` is the primary key of this timeline**: both authorizations and the settlement hang off the same Outstanding, so grouping by `outsId` matches authorizations to settlements — no guesswork needed.
* **Reversals also ask for your decision**: `INCOMING` releases are forwarded through `authUrl` too. DCS recommends simply returning `00` to approve; the only business reason to decline is an abnormal case such as a release larger than the amount currently frozen.
* **Settlement appears only in the daily files**: the capture on Day 4 produces no real-time callback, so your view of settled money comes entirely from the daily transaction report — which is exactly why end-of-day reconciliation is the source of truth for funds.
If the hotel had captured 75 or 60 instead of 70 on Day 4, DCS would automatically create a `FORCE_AUTH` to top up or release the difference, following scenarios 5/6 above; you would see that system-created record in the authorization report, with no real-time action needed on your side.
***
## What the partner does
| Step | Who does it | Description |
| ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Authorization decision (A/D) | **Partner** | DCS forwards the request over the authorization webhook, and the partner approves or declines based on its own limits and risk rules |
| Placing and releasing holds | **DCS** | Once the partner approves, DCS places the hold on the card network side and maintains the Outstanding |
| FORCE\_AUTH true-up | **DCS** | Back-filled automatically whenever settlement and hold disagree; no partner involvement needed |
| Settlement debit or refund | **DCS** | When network settlement arrives, DCS creates the transaction record and draws the Outstanding down |
| Reconciliation | **Partner** | Check the daily authorization report against the daily transaction report |
The request and response structures of the authorization webhook, the two-way RSA signing and the `responseCode` values (`00` approve, `01` insufficient funds, `11` transaction not allowed, `21` no response) are in [Webhook events and schema](../webhooks/events-and-schema).
***
## Next steps
* Want to verify these scenarios? Simulate an authorization in the sandbox: [Simulating transactions](../sandbox/simulating-transactions) (`POST /open-api/simulation/v1/fund-auth`, supporting `EXPEND` for a purchase, `REFUND` for a return and `REVERSAL` for a reversal).
* For the detail behind multiple and excess captures: [Capture scenarios](./capture-scenarios).
* For handling declined authorizations: [Authorization declines and error codes](./decline-codes).