> ## 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. # 授权（转发决策） > 说明接入机构如何接收授权请求、在规定时间内返回决策，并处理不同的 direction 和 authType。 ## 授权：把决策权交回您手里 无论您是想完全自管用户额度、还是按自己的风控规则逐笔放行交易，授权转发都让您在持卡人每一次刷卡的瞬间，亲自决定批准还是拒绝。DCS 是持牌发卡机构、自有 BIN，我们负责把卡组织的实时授权请求安全地转发给您，资金的冻结与解冻由我们代为执行——**额度由接入机构掌握，授权由接入机构决策**。 授权（Authorisation）发生在持卡人发起消费的那一刻，是一次实时决策，**不产生实际资金扣除**。真正的资金扣减发生在后续的清算环节（详见[交易流水](./transaction)与[授权与清算](./auth-and-settlement)）。 *** ## 一笔授权的处理流程 一笔授权的处理流程时序图 一笔授权的处理流程时序图 | 角色 | 谁做 | 职责 | | ------- | -------- | --------------------------- | | 转发授权请求 | **DCS** | 校验卡片状态，加密加签后推送到您的 `authUrl` | | 授权决策 | **接入机构** | 验签、解密，按企业保证金余额/风控规则返回同意或拒绝 | | 资金冻结/解冻 | **DCS** | 根据您的决策结果执行冻结或解冻，回应卡组织 | > 在合作伙伴自管模式下，决策权始终在接入机构；DCS 的转发通道额外做了 **RSA 双向加密 + 加签**，业务字段不以明文出现在请求体中。 *** ## 交易方向（direction） | 枚举值 | 名称 | 资金动作 | 典型场景 | | ---------- | -- | -------- | ------- | | `OUTGOING` | 出金 | 冻结用户对应金额 | 持卡人付款消费 | | `INCOMING` | 入金 | 解冻用户对应金额 | 撤销、退款 | > 退款有原授权、撤销等 `INCOMING` 授权同样经 `authUrl` 转发。DCS 建议接入机构对这类 `INCOMING` 授权直接返回 `00`（放行）；当 `INCOMING` 的解冻金额大于已冻结金额等异常场景时，接入机构可以拒绝该授权。 *** ## 授权类型（authType） `authType` 标识一条授权记录的产生方式，帮助接入机构区分「实时授权」与「系统补建/释放」。 | 枚举值 | 名称 | 是否经 `authUrl` | 说明 | | --------------------- | ------ | ------------- | ------------------------------------------- | | `NORMAL` | 普通授权 | 是 | 渠道实时授权回调产生的标准记录，涵盖消费、增量、撤销、退款、提现、查询等所有实时场景 | | `FORCE_AUTH` | 强制授权 | 否 | 系统自动补建的记录：清算时无对应授权（如离线交易），或清算金额与冻结金额不一致需补差额 | | `EXPIRED_RELEASE` | 到期释放 | 否 | 授权超时未完成结算，渠道通过结算文件通知释放已冻结资金 | | `STATUS_DIFF_RELEASE` | 状态差异释放 | 否 | 渠道因超时拒绝了授权但系统侧已批准，状态不一致时触发的对账修正 | 仅 `NORMAL` 类型授权经 `authUrl` 转发给接入机构实时决策；`FORCE_AUTH` / `EXPIRED_RELEASE` / `STATUS_DIFF_RELEASE` 为系统侧授权，不经 `authUrl`，只通过 `AUTHORISATION_RESULT` Webhook 推送回执。 该字段同时出现在 **Webhook 授权请求**与**每日授权报告**中（详见[授权报告](../reports/authorization-report)）。 授权转发通知中的 `authType` 与沙盒模拟接口 `APISimulationAuthRequest.authType`（`EXPEND`/`REFUND`/`REVERSAL`）是两套独立枚举，分别用于真实授权回调与沙盒触发，请勿混用。 *** ## 授权交易类型（transactionType） `transactionType` 标识持卡人这笔交易的性质，便于授权决策与对账分类。 | 枚举值 | 名称 | 说明 | | --- | ------ | -------------- | | `R` | 卡消费 | 所有卡消费交易 | | `C` | ATM 提现 | ATM 提现等现金预支交易 | | `Q` | 查询 | 查询类交易，无资金变动 | | `P` | 退货/退款 | 所有向卡入金的转账或退款交易 | *** ## 授权结果（responseCode）—— 接入机构的回应 接入机构完成决策后，把结果通过 `responseCode` 返回给 DCS： | `responseCode` | 含义 | | -------------- | -------- | | `"00"` | 同意 | | `"01"` | 拒绝，资金不足 | | `"11"` | 拒绝，交易不允许 | | `"21"` | 拒绝，无响应 | 授权转发通知的应答字段为 `responseCode`；事后记录规则固定为 `00 → approveFlag=A`，`01/11/21` 及其他非 `00` 值 → `approveFlag=D`。`approveFlag` 用于事后 Webhook 与每日授权报告。生产环境授权同步应答窗口统一为 **2.5 秒**，接入机构必须在该窗口内同步返回；超时按 `responseCode=21` / `DAPI_AUTH_ENTERPRISE_TIMEOUT_REJECT` 处理，实时授权不会重试。 *** ## 授权转发通知：安全交互规范（谁做什么） 授权请求并非普通 Webhook，而是一条经过 **RSA 双向加密 + 加签**的安全通道。所有业务字段都封装在 `encryptedData` 里，不以明文出现。 ### 前置条件（接入机构） * 已创建企业（Enterprise），并配置好 `authUrl` 与 `externalPublicKey`（您的 RSA 公钥）。详见[前置准备](../../getting-started/first-steps)。 * 已设置授权转发通知的 **IP 白名单**。 * 已成功[申请卡](../cards/card-issuing)。 > 沙盒环境的 DCS RSA 公钥可在[鉴权指南](../../integration-resources/authentication)页直接复制；生产环境公钥请联系 DCS 团队领取。 ### 完整流程 | 步骤 | 谁做 | 动作 | | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ① 发起通知 | **DCS** | 取 `authId`/`direction`/`currency`/`amount` 等业务字段，用**接入机构 RSA 公钥**加密 → Base64 放入 `data.encryptedData`；用 **DCS RSA 私钥**加签 → Base64 放入请求头 `X-Auth-Signature`；POST 到您的 `authUrl` | | ② 验签 | **接入机构** | 用 **DCS RSA 公钥**对 `X-Auth-Signature` 验签，失败即拒绝 | | ③ 解密 | **接入机构** | 用**接入机构 RSA 私钥**解密 `data.encryptedData`，得到明文业务字段 | | ④ 决策 | **接入机构** | 按企业保证金余额/风控规则生成 `responseCode` | | ⑤ 返回结果 | **接入机构** | 把 `{authId, responseCode}` 用 **DCS RSA 公钥**加密 → `encryptData`；用**接入机构 RSA 私钥**加签 → `signature`；返回给 DCS | | ⑥ 执行 | **DCS** | 验签+解密后，按 `responseCode` 冻结/解冻资金或终止交易 | 签名算法：**RSA-SHA256（`SHA256withRSA`）**；密钥长度 2048 位；加解密分段（加密块 245 字节 / 解密块 256 字节）。完整 Java 示例代码见[鉴权指南](../../integration-resources/authentication)页。 RSA 双向加密与加签流程 RSA 双向加密与加签流程 > 通知 URL 模板：`https://{domain}/xxx/v1/auth-notification`（DCS → 接入机构 `authUrl` 的 POST 请求）。 *** ## 请求与响应结构 ### 请求头 | 字段 | 类型 | 说明 | | ------------------ | ------ | --------------------------- | | `X-Auth-Signature` | string | 签名信息，Base64 编码后的 DCS 私钥加签结果 | ### 请求体 | 字段 | 类型 | 说明 | | -------------------- | ------ | ----------------------------------------- | | `webhookId` | string | Webhook 唯一标识，可据此去重避免重复消费 | | `webhookType` | string | 固定取值 `AUTHORISATION` | | `webhookSubType` | string | 子类型，例如 `CREATE` / `UPDATE` | | `businessId` | string | Webhook 内容 ID，例如 `authId` | | `data.authId` | string | 授权事件唯一编号 | | `data.encryptedData` | string | 加密后的全部授权业务字段（RSA + Base64），见下方 | | `notificationTime` | string | 通知时间，`yyyy-MM-dd'T'HH:mm:ss+08:00`（UTC+8） | **时区提示**：授权通知与对账文件中的时间字段均带 `+08:00` 偏移（UTC+8）；例外是卡限额查询接口的日期字段为 UTC。存储时请显式记录时区，避免跨接口比对错位。 ### `encryptedData` 解密后业务字段 | 字段 | 类型 | 说明 | | ---------------------------- | ---------- | ---------------------------------- | | `authId` | string | 授权唯一标识，关联后续交易与对账 | | `direction` | string | 交易方向 `OUTGOING` / `INCOMING` | | `authType` | string | 授权类型，见上文枚举 | | `outsId` | string | 账单（Outstanding）ID，首笔授权自动生成，串联授权与清算 | | `originalAuthId` | string | 原始关联授权 ID，增量/撤销等场景复用同一 Outstanding | | `customerId` | string | 持卡人用户 ID | | `cardId` | string | 发生授权的卡片 ID | | `currency` | string | 结算币种，ISO 3 位货币代码 | | `amount` | bigdecimal | 结算金额 | | `acquirerCurrency` | string | 用户请求币种（可能与结算币种不同） | | `acquirerAmount` | bigdecimal | 用户请求金额 | | `cardAcceptorIdentification` | string | 商户号，交易涉及的商户标识 | | `cardAcceptorNameLocation` | string | 商户名称与地址（结构见下） | | `merchantType` | string | 商户类型（MCC），4 位数字 | | `transactionType` | string | 交易类型 `R`/`C`/`Q`/`P`，见上文枚举 | #### `cardAcceptorNameLocation` 该字段为固定 40 字符的定长文本，各段内容左对齐、不足右补空格。 ##### Visa | 位置 | 长度 | 描述 | | ----- | -- | --------------------------------- | | 1–25 | 25 | 商户名称，持卡人可识别的名称 | | 26–38 | 13 | 商户所在城市 | | 39–40 | 2 | 商户所在国家 ISO 3166-1 二字符国家码（alpha-2） | ##### Mastercard | 位置 | 长度 | 描述 | | ----- | -- | --------------------------------- | | 1–22 | 22 | 商户名称，持卡人可识别的名称 | | 23 | 1 | 空格分隔符 | | 24–36 | 13 | 商户所在城市 | | 37 | 1 | 空格分隔符 | | 38–40 | 3 | 商户所在国家 ISO 3166-1 三字符国家码（alpha-3） | ### 响应体 | 字段 | 类型 | 说明 | | ------------- | ------ | --------------------------------------------- | | `signature` | string | 响应内容签名，Base64 编码的接入机构私钥加签结果 | | `encryptData` | string | 加密后的响应数据（`authId` + `responseCode`），Base64 编码 | `encryptData` 解密后结构： | 字段 | 类型 | 说明 | | -------------- | ------ | -------- | | `authId` | string | 授权 ID | | `responseCode` | string | 授权结果，见上文 | 请求侧加密字段为 `data.encryptedData`（位于 `data` 对象内），响应侧加密字段为 `encryptData`（顶层、命名不同），两者命名不一致，集成时请按各自结构取值，勿混用。 *** ## 授权请求体最小示例 ```json theme={null} { "webhookId": "wh_20260616_0001", "webhookType": "AUTHORISATION", "webhookSubType": "CREATE", "businessId": "auth_8f3c...", "data": { "authId": "auth_8f3c...", "encryptedData": "Base64(RSA(接入机构公钥, 业务字段JSON))" }, "notificationTime": "2026-06-16T14:23:05+08:00" } ``` 响应（接入机构 → DCS）： ```json theme={null} { "encryptData": "Base64(RSA(DCS公钥, {\"authId\":\"auth_8f3c...\",\"responseCode\":\"00\"}))", "signature": "Base64(SHA256withRSA(接入机构私钥, encryptData))" } ``` > 该授权转发通知是 DCS → 接入机构 `authUrl` 的**独立安全通道**，不使用 `/open-api/` 业务接口的统一响应结构 `{code, message, messageDetail, data}`。该响应结构用于您主动发起的业务接口，详见[鉴权指南](../../integration-resources/authentication)。 *** ## 跟一笔授权走一遍 以一笔真实形态的消费为例，把上述字段与流程串起来：您的持卡人持一张 USD 卡，在东京一家超市刷卡消费 3,000 JPY。 | 时刻 | 发生什么 | 您收到 / 返回什么 | | --------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | T+0ms | 持卡人刷卡，卡组织把授权请求路由到 DCS；DCS 校验卡片状态（激活、未冻结） | — | | T+\~100ms | DCS 加密加签后 POST 您的 `authUrl` | 请求：`direction=OUTGOING`、`authType=NORMAL`、`transactionType=R`、`acquirerCurrency=JPY`、`acquirerAmount=3000`、`currency=USD`、`amount=20.45`、`merchantType=5411`、`outsId=outs_71ab...` | | T+2.5s 内 | 您验签、解密，校验用户额度与风控规则后作出决策 | 返回：`{authId, responseCode: "00"}`（加密加签） | | T+\~2.5s | DCS 冻结 20.45 USD，Outstanding `outs_71ab...` 记为 20.45，回应卡组织，持卡人侧交易成功 | — | | 随后 | DCS 推送授权结果回执 | `AUTHORISATION_RESULT` Webhook：`approveFlag=A`、同一 `authId` / `outsId` | | 次日 | 这笔授权进入每日授权报告，供您对账 | 报告行：`authId`、`approveFlag=A`、金额与商户字段 | 三个值得注意的细节： * **两组金额字段不是重复**：`acquirerAmount/acquirerCurrency`（3,000 JPY）是持卡人在商户侧的原始消费，`amount/currency`（20.45 USD）是按卡组织汇率折算后的结算口径——冻结、清算与对账都以结算口径为准。 * **您只做决策，不动资金**：返回 `00` 之后的冻结由 DCS 在卡组织侧完成；若您返回 `01`（资金不足）或 `11`（交易不允许），流程在第三行终止，持卡人侧显示交易失败，不产生任何资金动作。 * **决策窗口是 2.5 秒**：超时按 `21`（无响应）拒绝处理，实时授权不会重试，请把验签、解密与额度校验的整链路耗时控制在窗口内。 这笔交易的资金生命周期到这里只完成了一半——冻结中的 20.45 USD 如何在清算日真正扣款、清算金额与冻结不一致时怎么办，见[授权与清算全场景](./auth-and-settlement)。 *** ## 与授权相关联的模块 * **企业主体（Enterprise）**：授权决策由接入机构完成；资金冻结/解冻关联**企业保证金**账户或其维护的持卡人额度。 * **卡片（Card）**：授权请求绑定 `cardId`，卡片激活/冻结/注销状态直接影响授权有效性；冻结卡片会触发授权释放。 * **Outstanding（账单）**：连接授权与清算的桥梁——授权阶段累加冻结金额，清算阶段扣减至零。详见[授权与清算](./auth-and-settlement)。 * **交易流水（Transaction）**：授权是交易的前置环节，一笔流水可关联多个 `authId`，仅授权通过的交易才生成资金流转记录。 *** ## 下一步 * 想先在沙盒里跑通一笔授权而不接卡组织？用[沙盒·模拟交易](../sandbox/simulating-transactions)的 `POST /open-api/simulation/v1/fund-auth` 触发一笔授权（请求参数 `cardId`/`authType`/`amount`/`currency`，返回 `approved` + `errorCode`）。 * 想了解授权之后资金如何清算？见[授权与清算](./auth-and-settlement)。 * 想配置 Webhook 与各类事件？见[Webhook·配置](../webhooks/configuration)。 * 拒绝原因与错误码对照，见[授权拒绝与错误码](./decline-codes)。