> ## 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 (handled inside DCS, no partner decision required)
> The how-to page for the authorization stage: how an authorization is completed inside DCS in the DeCard-Managed model, what you have to do, and how to verify it in the sandbox. For the mental model of the transaction flow (authorization then settlement, Outstanding, invariants), see the concept page Transaction Lifecycle · Overview.
## Authorization: DCS decides for you, in real time, inside the system
In the DeCard-Managed model, DCS makes every authorization decision for you in real time: it checks the card status, the available balance and the limits, then approves or declines on the spot, with no per-transaction response from you. As a licensed issuer running its own BINs, DCS connects directly to the card networks and holds the cardholder's own balance in custody, which takes the most latency-sensitive and reconciliation-sensitive question in the whole flow, whether to let a payment through at the moment the card is presented, off your integration list entirely.
Precisely because the decision happens inside DCS, the authorization decision needs no integration work on your side: there is no `auth_url`, no per-transaction response and no authorization decision webhook to register. This page explains how the mechanism works and the few things you actually need to do; for the mental model of the transaction flow (the two stages of authorization and settlement, the Outstanding bridge, the invariants), see the concept page [Transaction Lifecycle · Overview](../../basic-concepts/transaction-lifecycle).
## How DeCard-Managed differs from Partner-Managed
| Dimension | Partner-Managed | **DeCard-Managed (this documentation set)** |
| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Who makes the authorization decision | The partner (you) approves or declines each transaction | **DCS, inside its own system** |
| Is an authorization decision webhook required | Yes (if you do not respond, the default settings apply) | **No, this integration item does not exist** |
| Where the balance or limit lives | Your reserve, in your own ledger | **Per-user balances held in custody by DCS** (`free` / `freeze`) |
| What you receive | A synchronous authorization request for you to decide on | A **notification** of the authorization result (`CARD_TRANSACTION` / `BALANCE_CHANGE` webhook) |
In the DeCard-Managed model, therefore, **do not** try to configure default authorization settings or register an authorization webhook to approve and decline: there is **no** authorization forwarding endpoint, decision callback or `auth_url` configuration here. If you genuinely need to own the authorization decision, that is the **Partner-Managed** model and is out of scope for this documentation set.
## How an authorization is handled in the DeCard-Managed model
The moment the cardholder swipes, taps or inserts the card, the merchant requests authorization from the card network and DCS decides internally:
1. **System checks** (any failure results in a decline):
* the card status must allow transactions (not `FROZEN`, not `CANCELLED`);
* the user's transaction status, since card transactions are blocked for that user when `forbidCardTransaction = true` in `GET /account/v1/user-status`;
* the user's **available balance** (`free`) must fully cover the authorization amount;
* card-level and user-level limits and risk rules.
2. **Funds are frozen** (no actual deduction takes place): on approval the corresponding amount moves from available to frozen, so `free` decreases, `freeze` increases and `total` is unchanged.
3. **Result notification**: DCS notifies the authorization result through the `CARD_TRANSACTION` webhook (`response` = `A` for approved, `D` for declined) and the balance change through the `BALANCE_CHANGE` webhook (`freeDelta` \< 0, `freezeDelta` > 0).
4. **Settlement follows**: once the merchant submits the final amount, settlement releases the hold and performs the actual deduction.
> Both steps that really change a user's balance, the freeze at authorization and the deduction at settlement, land on **that user's own account held in custody by DCS**. That is what fundamentally separates this model from Partner-Managed, where the reserve sits with the partner. For details, see [Account and Asset Model (Ledgering)](../../basic-concepts/ledgering-system).
### The journey of one authorization
### The two notifications you receive (key fields)
Authorization results reach you as two kinds of webhook or WebSocket event. The fields below are the ones most used for reconciliation; the full detail lives in [Webhook & WebSocket](../../integration-resources/webhook-websocket) and on the concept page:
| Event `type` | Field | Meaning |
| ------------------ | --------------------------- | ------------------------------------------------------------------------ |
| `CARD_TRANSACTION` | `response` | Authorization result: `A` = approved / `D` = declined |
| `CARD_TRANSACTION` | `authType` | `EXPEND` (purchase) / `REFUND` (return) / `REVERSAL` (purchase reversal) |
| `CARD_TRANSACTION` | `amount` / `currency` | Authorization amount / currency |
| `CARD_TRANSACTION` | `cardId` / `externalUserId` | The card and user involved |
| `BALANCE_CHANGE` | `freeDelta` | Change in available balance (negative when an authorization is approved) |
| `BALANCE_CHANGE` | `freezeDelta` | Change in frozen balance (positive when an authorization is approved) |
| `BALANCE_CHANGE` | `free` / `freeze` | Absolute available and frozen balances after the change |
The full field tables for both webhooks are in the "Authorization webhook field definitions" section below; the step-by-step sequences for the three `authType` values are in "The three scenarios by authType".
## What you need to do
| Scenario | What you do |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization decision | **Nothing**, DCS decides internally and you never respond per transaction |
| Receiving authorization results | Configure a webhook receiver for `CARD_TRANSACTION` and use it to post to your books or notify the user. See [Webhook & WebSocket](../../integration-resources/webhook-websocket) |
| Keeping the card authorizable | Make sure the user account holds enough `free` balance (top it up) and that `forbidCardTransaction` is not set |
| Balance operations | Top up with `user-asset/v1/credit`, deduct with `user-asset/v1/debit` and read balances with `user-asset/v1/balance`. See [User Balance](./user-balance) |
> In other words, whether an authorization succeeds depends mainly on **whether the user's own balance is sufficient** and **whether card transactions are blocked for that user**, not on any response from you.
## Verifying an authorization in the sandbox (no card network needed)
Without connecting to a card network, you can trigger an authorization through the **sandbox simulation** endpoints and verify your webhook handling and balance logic:
**`POST /simulation/v2/fund-auth`**
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `externalUserId` | string | Yes | External user ID (redacted placeholder ``) |
| `cardId` | string | Yes | Card ID |
| `authType` | string | Yes | `EXPEND` (purchase) / `REFUND` (return) / `REVERSAL` (purchase reversal) |
| `amount` | number | Yes | Amount, as a decimal |
| `currency` | string | Yes | Transaction currency (USD, RMB, SGD, EUR, JPY and so on) |
These are **sandbox simulation** endpoints, **not production authorization decision endpoints**. The DeCard-Managed model has no production authorization API for a partner to decide on.
The response envelope is the site-wide `{code, message, messageDetail, data}`, with the success code literal `SYS_SUCCESS`:
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "...",
"messageDetail": {
"message": "", "title": "", "type": "", "icon": "",
"action": "", "linkTitle": "", "linkUrl": ""
},
"data": {
"approved": true,
"errorCode": ""
}
}
```
* `data.approved` (boolean): whether the authorization was approved.
* `data.errorCode` (string): the error code when it was not.
* `messageDetail`: an optional display object whose fields are usually empty strings on success.
> For more `fund-auth` sandbox scenarios, see [Simulating Transactions](../simulating-transactions/overview).
## Authorization webhook field definitions
Authorization results and balance changes reach the partner through two webhooks. Authorization transaction fields always come from `CARD_TRANSACTION`; balance changes always come from `BALANCE_CHANGE`.
### CARD\_TRANSACTION (authorization transaction, all fields)
The fields are as follows:
| Field | Type | Description |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardNumber` | string | Last 4 digits of the card number |
| `transactionCurrencyCode` | string | ISO code of the transaction currency (for example `"840"` or `"702"`) |
| `transactionAmount` | BigDecimal | Transaction amount |
| `localTransactionDate` | string | Transaction date (for example `"1211"`) |
| `localTransactionTime` | string | Transaction time (for example `"161420"`) |
| `response` | string | Transaction result: `A` (accept/success) / `D` (deny/fail) |
| `externalTranId` | Long | External transaction ID |
| `systemTraceAuditNumber` | string | System trace audit number |
| `requestAmountInUsd` | string | Transaction amount in USD |
| `mcc` | string | Merchant Category Code |
| `cardAcceptorNameLocation` | string | Merchant name and location |
| `direction` | string | Direction of funds: `DEBIT` (deduction, a purchase) / `CREDIT` (credit, a refund) |
| `settlementCurrencyCode` | string | Posting currency of the card account (ISO 4217, for example `"840"`) |
| `settlementAmount` | BigDecimal | Posting amount on the card account |
| `transactionType` | string | Transaction type: `R` card purchase / `C` ATM withdrawal / `Q` enquiry / `P` transfer or refund |
| `merchantCountryCode` | string | Merchant country code (3 digits) |
| `originalExternalTranId` | string | External transaction ID of the original transaction, **returned only for reversing transactions** (void, reversal, refund and so on); ordinary authorizations do not carry this field |
> Direction is expressed by `direction` (DEBIT/CREDIT); the nature of the transaction is expressed by `transactionType` (R/C/Q/P).
### BALANCE\_CHANGE (balance change, all fields)
An approved authorization freezes funds: the money never leaves the account, it only moves between the **available** and **frozen** columns, and the real deduction happens later at settlement (see [Settlement](./settlement)). That movement is notified through `BALANCE_CHANGE`:
| Field | Type | Description |
| ---------------- | ---------- | ----------------------------------------------------------------------------------- |
| `tranId` | Long | Ledger entry number |
| `externalTranId` | string | External transaction ID |
| `asset` | string | Asset currency |
| `network` | string | Network (empty for fiat and internal movements) |
| `freeDelta` | BigDecimal | Change in the available position (**negative** when an authorization freezes funds) |
| `freezeDelta` | BigDecimal | Change in the frozen position (**positive** when an authorization freezes funds) |
| `free` | BigDecimal | Available position after the change |
| `freeze` | BigDecimal | Frozen position after the change |
| `type` | string | Movement type (such as `CONVERSION`) |
An example (redacted; the semantics are a hold of 2.92, available -2.92 and frozen +2.92):
```json theme={null}
{
"webhookId": "",
"type": "BALANCE_CHANGE",
"externalUserId": "",
"notificationTimestamp": 1767777763336,
"eventTimestamp": 1767777641000,
"data": {
"asset": "USD",
"network": "",
"freeDelta": -2.92,
"freezeDelta": 2.92,
"tranId": 4862356405699379969,
"externalTranId": "4862356404793410306",
"free": 0,
"freeze": 18.1,
"type": "CONVERSION"
}
}
```
> For the overall model behind available and frozen balances (`free` / `freeze` / `total`) and the custody strategies, see [Account and Asset Model (Ledgering)](../../basic-concepts/ledgering-system).
## Authorization types (authType)
`authType` states the nature of an authorization. The DeCard-Managed model uses only the following three:
| Enum value | Name | Description |
| ---------- | ----------------- | ----------------------------------------------------------------- |
| `EXPEND` | Purchase | The cardholder pays, and the corresponding amount is frozen |
| `REFUND` | Return | A credit for a return (the final credit is applied at settlement) |
| `REVERSAL` | Purchase reversal | A reversal (void) of the original purchase authorization |
## The three scenarios by authType
The three `authType` values differ in how they affect the account and which webhooks you receive.
### EXPEND, a purchase
* Approved: the available balance decreases and the frozen balance increases, with `response=A` and `direction=DEBIT`.
* Declined: insufficient balance, a card that cannot transact, `forbidCardTransaction=true` and similar cases give `response=D` and create no hold.
### REFUND, a return
* A return credits the card, so `direction=CREDIT` and `transactionType=P`, and `originalExternalTranId` is returned to link back to the original transaction.
* The credited amount only reaches the user's available balance once **settlement** completes (see [Settlement](./settlement)).
### REVERSAL, a purchase reversal
* A reversal of the original purchase authorization returns `direction=CREDIT` and `originalExternalTranId`, and releases the amount frozen by the earlier `EXPEND` (frozen back to available).
* The exact values of `direction` and `transactionType` are whatever the `CARD_TRANSACTION` webhook actually returns.
## About 3DS
3DS strong authentication is part of the authorization path and is completed by DCS on the issuing side; see [3DS strong authentication](./3ds-forwarding).
## Next steps
* Mental model of the transaction flow (the two stages, the Outstanding bridge, the invariants): [Transaction Lifecycle · Overview](../../basic-concepts/transaction-lifecycle)
* Account and asset model (`free` / `freeze` / `total`): [Account and Asset Model (Ledgering)](../../basic-concepts/ledgering-system)
* Reading and adjusting user balances: [User Balance](./user-balance)
* How funds are actually posted after authorization: [Settlement](./settlement)
* Receiving authorization result notifications: [Webhook & WebSocket](../../integration-resources/webhook-websocket)
* Simulating an authorization in the sandbox: [Simulating Transactions](../simulating-transactions/overview)