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

# 授权（系统内完成，无需接入机构决策）

> 说明 DeCard 托管模式下一笔授权如何在系统内完成、接入机构需要做什么，以及如何在沙盒中验证。授权与清算的整体关系见交易生命周期。

## 授权：DCS 在系统内为您实时拍板

在 DeCard 托管模式下，DCS 在系统内为您实时完成每一笔授权决策——校验卡状态、可用余额与限额后即时批准或拒绝，您无需逐笔返回结果。作为持牌发卡机构、自有 BIN，DCS 直接对接卡组织、托管用户的独立余额，把「持卡人刷卡的瞬间该不该放行」这件最实时、最考验风控与资金对账的事，从您的接入清单里整个拿掉。

由于决策在系统内完成，DeCard 托管模式不要求您接入 `auth_url`、逐笔返回授权结果或注册授权决策 Webhook。本页说明这套机制及接入机构需要完成的操作；授权与清算的整体关系见[交易生命周期](../../basic-concepts/transaction-lifecycle)。

## DeCard 托管与合作伙伴自管的本质区别

| 维度                  | 合作伙伴自管                      | **DeCard 托管（本套文档）**                                       |
| ------------------- | --------------------------- | --------------------------------------------------------- |
| 谁做授权决策              | 接入机构（您）逐笔 approve / decline | **DCS 系统内部完成**                                            |
| 是否需注册「授权决策 Webhook」 | 是（不响应则走默认设置）                | **否——不存在该接入项**                                            |
| 余额 / 额度在哪           | 您侧 reserve / 接入机构账本         | **DCS 托管的用户独立余额**（`free` / `freeze`）                      |
| 您收到的是什么             | 同步授权请求（请您拍板）                | 授权结果**通知**（`CARD_TRANSACTION` / `BALANCE_CHANGE` Webhook） |

<Warning>
  因此，DeCard 托管下**请勿**去「配置默认授权设置」或「注册授权 Webhook 来 approve/decline」——DeCard 托管**没有**授权转发接口、决策回调或 `auth_url` 配置。若您确需自管授权决策，那属于 **合作伙伴自管方案**，不在 DeCard 托管范围内。
</Warning>

## DeCard 托管下，一笔授权如何被处理（要点）

持卡人刷卡 / Tap / 插卡的那一刻，商户向卡网络请求授权，DCS 在系统内完成判定：

1. **系统校验**（任一不满足即拒绝）：
   * 卡片状态须可交易（非 `FROZEN` / 非 `CANCELLED`）；
   * 用户交易状态——`GET /account/v1/user-status` 的 `forbidCardTransaction = true` 时该用户卡交易被禁止；
   * 用户**可用余额**（`free`）须足额覆盖授权金额；
   * 卡 / 用户级限额与风控规则。
2. **冻结资金**（不发生实际扣款）：授权通过时把对应金额从「可用」移入「冻结」——`free` 减少、`freeze` 增加、`total` 不变。
3. **结果通知**：DCS 通过 `CARD_TRANSACTION` Webhook 通知授权结果（`response` = `A` 通过 / `D` 拒绝），通过 `BALANCE_CHANGE` Webhook 通知余额变动（`freeDelta` \< 0、`freezeDelta` > 0）。
4. **后续清算**：商户提交最终金额后，在清算阶段释放冻结并完成实际扣减。

> 真正改变用户余额的两步——授权时冻结、清算时扣减——都落在 **DCS 托管的该用户独立账户** 上。这是 DeCard 托管区别于合作伙伴自管（接入机构 reserve）的本质。详见 [账户与资产模型](../../basic-concepts/ledgering-system)。

### 一次授权的旅程

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-auth-journey-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=60304638cb05a4801bfaab3ed77ca47d" alt="DCS 托管授权决策流程" width="700" height="770" data-path="imgs/diagrams/va-auth-journey-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-auth-journey-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=4a3f5ea9974c0a582b80b13e09a32f3b" alt="DCS 托管授权决策流程" width="700" height="770" data-path="imgs/diagrams/va-auth-journey-dark.svg" />
</Frame>

### 您会收到的两类通知（关键字段）

授权结果以两类 Webhook / WebSocket 事件推送给您；以下为对账最常用的字段，明细仍以 [Webhook 与 WebSocket 实时通知](../../integration-resources/webhook-websocket) 与概念页为准：

| 事件 `type`          | 字段                          | 含义                                           |
| ------------------ | --------------------------- | -------------------------------------------- |
| `CARD_TRANSACTION` | `response`                  | 授权结果：`A` = 通过 / `D` = 拒绝                     |
| `CARD_TRANSACTION` | `authType`                  | `EXPEND`（消费）/ `REFUND`（退货）/ `REVERSAL`（消费冲正） |
| `CARD_TRANSACTION` | `amount` / `currency`       | 授权金额 / 币种                                    |
| `CARD_TRANSACTION` | `cardId` / `externalUserId` | 关联的卡 / 用户                                    |
| `BALANCE_CHANGE`   | `freeDelta`                 | 可用余额变动（授权通过时为负）                              |
| `BALANCE_CHANGE`   | `freezeDelta`               | 冻结余额变动（授权通过时为正）                              |
| `BALANCE_CHANGE`   | `free` / `freeze`           | 变动后的可用 / 冻结余额绝对值                             |

两类 Webhook 的完整字段表见下文「授权 Webhook 字段定义」一节；`authType` 三类场景的逐步时序见「按 authType 看三类场景」一节。

## 接入机构需要做什么

| 场景     | 您要做的                                                                                                                             |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| 授权决策   | **无**——DCS 系统内完成，您无需逐笔返回结果                                                                                                       |
| 接收授权结果 | 配置 Webhook 接收端（接收 `CARD_TRANSACTION`），按需做记账 / 通知用户。配置见 [Webhook 与 WebSocket 实时通知](../../integration-resources/webhook-websocket) |
| 保证可授权  | 确保用户账户有足额 `free` 余额（充值），并确认 `forbidCardTransaction` 未置位                                                                          |
| 余额运营   | 通过 `user-asset/v1/credit` 充值、`user-asset/v1/debit` 扣款、`user-asset/v1/balance` 查询余额——见 [用户余额](./user-balance)                     |

> 也就是说，授权「成不成」主要取决于**用户独立余额是否足额**与**用户交易状态是否被禁**，而非您是否返回结果。

## 在沙盒里验证一笔授权（无需接卡组织）

在不接卡组织的情况下，您可用**沙盒模拟**接口触发一笔授权，验证您的 Webhook 与余额变动逻辑：

**`POST /simulation/v2/fund-auth`**

| 请求参数             | 类型     | 必填 | 说明                                           |
| ---------------- | ------ | -- | -------------------------------------------- |
| `externalUserId` | string | 是  | 外部用户 ID（脱敏占位 `<external-user-id>`）           |
| `cardId`         | string | 是  | 卡 ID                                         |
| `authType`       | string | 是  | `EXPEND`（消费）/ `REFUND`（退货）/ `REVERSAL`（消费冲正） |
| `amount`         | number | 是  | 金额（小数形式）                                     |
| `currency`       | string | 是  | 交易币种（USD / RMB / SGD / EUR / JPY 等）          |

<Warning>
  这是**沙盒模拟授权**接口，**不是生产期的授权决策接口**——DeCard 托管不存在让接入机构拍板的生产授权 API。
</Warning>

响应结构统一为 `{code, message, messageDetail, data}`，成功码字面量为 `SYS_SUCCESS`：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "...",
  "messageDetail": {
    "message": "", "title": "", "type": "", "icon": "",
    "action": "", "linkTitle": "", "linkUrl": ""
  },
  "data": {
    "approved": true,
    "errorCode": ""
  }
}
```

* `data.approved`（boolean）：是否授权通过。
* `data.errorCode`（string）：未通过时的错误码。
* `messageDetail`：可选展示对象，成功时各字段通常为空字符串。

> `fund-auth` 的更多沙盒场景见 [模拟交易（沙盒）](../simulating-transactions/overview)。

## 授权 Webhook 字段定义

授权结果与余额变动以两类 Webhook 通知接入机构。授权交易字段一律以 `CARD_TRANSACTION` 为准；余额变动以 `BALANCE_CHANGE` 为准。

### CARD\_TRANSACTION（授权交易，全字段）

字段如下：

| 字段                         | 类型         | 说明                                                |
| -------------------------- | ---------- | ------------------------------------------------- |
| `cardNumber`               | string     | 卡号后 4 位                                           |
| `transactionCurrencyCode`  | string     | 交易币种 ISO 代码（如 `"840"`、`"702"`）                    |
| `transactionAmount`        | BigDecimal | 交易金额                                              |
| `localTransactionDate`     | string     | 交易日期（如 `"1211"`）                                  |
| `localTransactionTime`     | string     | 交易时间（如 `"161420"`）                                |
| `response`                 | string     | 交易结果：`A`（accept/success）/ `D`（deny/fail）          |
| `externalTranId`           | Long       | 外部交易 ID                                           |
| `systemTraceAuditNumber`   | string     | 系统跟踪号                                             |
| `requestAmountInUsd`       | string     | 美元交易金额                                            |
| `mcc`                      | string     | 商户类别码                                             |
| `cardAcceptorNameLocation` | string     | 商户名称和位置信息                                         |
| `direction`                | string     | 资金流向：`DEBIT`（扣款/消费）/ `CREDIT`（入账/退款）              |
| `settlementCurrencyCode`   | string     | 卡账户记账币种（ISO 4217，如 `"840"`）                       |
| `settlementAmount`         | BigDecimal | 卡账户记账金额                                           |
| `transactionType`          | string     | 交易类型：`R`-卡消费 / `C`-ATM 提现 / `Q`-查询类交易 / `P`-转账或退款 |
| `merchantCountryCode`      | string     | 商户国家代码（3 位数字）                                     |
| `originalExternalTranId`   | string     | 原始交易的外部交易 ID，**仅反交易场景返回**（撤销、冲正、退款等），普通授权交易不含此字段  |

> 方向以 `direction`（DEBIT/CREDIT）表达，交易性质以 `transactionType`（R/C/Q/P）表达。

### BALANCE\_CHANGE（余额变动，全字段）

授权通过即冻结资金——资金不离开账户，只是在**可用**与**冻结**两栏之间移动；真正的扣减发生在后续清算阶段（见 [清算](./settlement)）。该变动通过 `BALANCE_CHANGE` 通知：

| 字段               | 类型         | 说明                    |
| ---------------- | ---------- | --------------------- |
| `tranId`         | Long       | 流水单号                  |
| `externalTranId` | string     | 外部交易 ID               |
| `asset`          | string     | 资产币种                  |
| `network`        | string     | 网络（法币 / 内部变动场景为空）     |
| `freeDelta`      | BigDecimal | 可用持仓变动数量（授权冻结时为**负**） |
| `freezeDelta`    | BigDecimal | 冻结资产变动数量（授权冻结时为**正**） |
| `free`           | BigDecimal | 变动后可用持仓               |
| `freeze`         | BigDecimal | 变动后冻结资产               |
| `type`           | string     | 变动类型（如 `CONVERSION`）  |

示例（脱敏，冻结一笔 2.92 的语义：可用 -2.92 / 冻结 +2.92）：

```json theme={null}
{
  "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"
  }
}
```

> 可用 / 冻结余额（`free` / `freeze` / `total`）的整体模型与托管策略，见 [账户与资产模型](../../basic-concepts/ledgering-system)。

## 授权类型（authType）全表

`authType` 标识一笔授权的性质。DeCard 托管模式仅使用以下三种：

| 枚举值        | 名称   | 说明               |
| ---------- | ---- | ---------------- |
| `EXPEND`   | 消费   | 持卡人付款消费，冻结对应金额   |
| `REFUND`   | 退货   | 退货入账（最终入账在清算时完成） |
| `REVERSAL` | 消费冲正 | 对原消费授权的冲正（撤销）    |

## 按 authType 看三类场景

下面按三类 `authType` 分述对账户与 Webhook 的影响。

### EXPEND 消费

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-expend-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=7e8ed05cf9eee60de619d795be835052" alt="沙盒消费授权模拟流程" width="638" height="474" data-path="imgs/diagrams/va-sim-expend-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-expend-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=f40cad989ce2751d21de4ba539681212" alt="沙盒消费授权模拟流程" width="638" height="474" data-path="imgs/diagrams/va-sim-expend-dark.svg" />
</Frame>

* 通过：可用余额减少、冻结余额增加，`response=A`、`direction=DEBIT`。
* 拒绝：余额不足 / 卡不可交易 / `forbidCardTransaction=true` 等，`response=D`，不产生冻结。

### REFUND 退货

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-refund-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=94c9b8b9a7ce0e9acd5bb6fcff9461df" alt="沙盒退款授权模拟流程" width="638" height="354" data-path="imgs/diagrams/va-sim-refund-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-refund-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=c2a5fa14a7da0d80247bfe3ddffb3656" alt="沙盒退款授权模拟流程" width="638" height="354" data-path="imgs/diagrams/va-sim-refund-dark.svg" />
</Frame>

* 退货是给卡上入账，`direction=CREDIT`、`transactionType=P`，并返回 `originalExternalTranId`（关联原始交易）。
* 入账金额在**清算**完成时才真正落到用户可用余额（见 [清算](./settlement)）。

### REVERSAL 消费冲正

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-reversal-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=22d72ed26ded873d8ce12ec12add2bb0" alt="沙盒冲正模拟流程" width="638" height="474" data-path="imgs/diagrams/va-sim-reversal-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-sim-reversal-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=d91cea6c35caeb20c61a23d38ca6caf1" alt="沙盒冲正模拟流程" width="638" height="474" data-path="imgs/diagrams/va-sim-reversal-dark.svg" />
</Frame>

* 对原消费授权的冲正，`direction=CREDIT`、返回 `originalExternalTranId`，对应释放之前 `EXPEND` 冻结的金额（冻结 → 可用）。
* `direction` 与 `transactionType` 的具体取值以 `CARD_TRANSACTION` Webhook 实际返回为准。

## 关于 3DS

3DS 强认证是授权流程的一环，由 DCS 在发卡侧完成，详见 [3DS 强认证](./3ds-forwarding)。

## 下一步

* 授权与清算的交易主线：[交易生命周期 · 概述](../../basic-concepts/transaction-lifecycle)
* 账户与资产模型（`free` / `freeze` / `total`）：[账户与资产模型](../../basic-concepts/ledgering-system)
* 查询 / 调整用户余额：[用户余额](./user-balance)
* 授权之后如何实际入账：[清算](./settlement)
* 接收授权结果通知：[Webhook 与 WebSocket 实时通知](../../integration-resources/webhook-websocket)
* 沙盒模拟授权：[模拟交易（沙盒）](../simulating-transactions/overview)