Authorization (handled inside DCS, no partner decision required)

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.

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:

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.
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.
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).
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).

The journey of one authorization

DeCard-Managed authorization decision flow

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 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
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

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 `<external-user-id>`)
`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:

{
  "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.

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). 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):

{
  "webhookId": "<webhook-id>",
  "type": "BALANCE_CHANGE",
  "externalUserId": "<external-user-id>",
  "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).

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

Sandbox purchase authorization simulation

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).

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.

Next steps

Mental model of the transaction flow (the two stages, the Outstanding bridge, the invariants): Transaction Lifecycle · Overview
Account and asset model (free / freeze / total): Account and Asset Model (Ledgering)
Reading and adjusting user balances: User Balance
How funds are actually posted after authorization: Settlement
Receiving authorization result notifications: Webhook & WebSocket
Simulating an authorization in the sandbox: Simulating Transactions

​Authorization: DCS decides for you, in real time, inside the system

​How DeCard-Managed differs from Partner-Managed

​How an authorization is handled in the DeCard-Managed model

​The journey of one authorization

​The two notifications you receive (key fields)

​What you need to do

​Verifying an authorization in the sandbox (no card network needed)

​Authorization webhook field definitions

​CARD_TRANSACTION (authorization transaction, all fields)

​BALANCE_CHANGE (balance change, all fields)

​Authorization types (authType)

​The three scenarios by authType

​EXPEND, a purchase

​REFUND, a return

​REVERSAL, a purchase reversal

​About 3DS

​Next steps

Authorization: DCS decides for you, in real time, inside the system

How DeCard-Managed differs from Partner-Managed

How an authorization is handled in the DeCard-Managed model

The journey of one authorization

The two notifications you receive (key fields)

What you need to do

Verifying an authorization in the sandbox (no card network needed)

Authorization webhook field definitions

CARD_TRANSACTION (authorization transaction, all fields)

BALANCE_CHANGE (balance change, all fields)

Authorization types (authType)

The three scenarios by authType

EXPEND, a purchase

REFUND, a return

REVERSAL, a purchase reversal

About 3DS

Next steps