授权（转发决策） - DCS Technical Documentation

授权：把决策权交回您手里

无论您是想完全自管用户额度、还是按自己的风控规则逐笔放行交易，授权转发都让您在持卡人每一次刷卡的瞬间，亲自决定批准还是拒绝。DCS 是持牌发卡机构、自有 BIN，我们负责把卡组织的实时授权请求安全地转发给您，资金的冻结与解冻由我们代为执行——额度由接入机构掌握，授权由接入机构决策。授权（Authorisation）发生在持卡人发起消费的那一刻，是一次实时决策，不产生实际资金扣除。真正的资金扣减发生在后续的清算环节（详见交易流水与授权与清算）。

一笔授权的处理流程

角色	谁做	职责
转发授权请求	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 授权请求与每日授权报告中（详见授权报告）。

授权转发通知中的 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 公钥）。详见前置准备。
已设置授权转发通知的 IP 白名单。
已成功申请卡。

沙盒环境的 DCS RSA 公钥可在鉴权指南页直接复制；生产环境公钥请联系 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 示例代码见鉴权指南页。

通知 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（顶层、命名不同），两者命名不一致，集成时请按各自结构取值，勿混用。

授权请求体最小示例

{
  "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）：

{
  "encryptData": "Base64(RSA(DCS公钥, {\"authId\":\"auth_8f3c...\",\"responseCode\":\"00\"}))",
  "signature": "Base64(SHA256withRSA(接入机构私钥, encryptData))"
}

该授权转发通知是 DCS → 接入机构 authUrl 的独立安全通道，不使用 /open-api/ 业务接口的统一响应结构 {code, message, messageDetail, data}。该响应结构用于您主动发起的业务接口，详见鉴权指南。

跟一笔授权走一遍

以一笔真实形态的消费为例，把上述字段与流程串起来：您的持卡人持一张 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 如何在清算日真正扣款、清算金额与冻结不一致时怎么办，见授权与清算全场景。

与授权相关联的模块

企业主体（Enterprise）：授权决策由接入机构完成；资金冻结/解冻关联企业保证金账户或其维护的持卡人额度。
卡片（Card）：授权请求绑定 cardId，卡片激活/冻结/注销状态直接影响授权有效性；冻结卡片会触发授权释放。
Outstanding（账单）：连接授权与清算的桥梁——授权阶段累加冻结金额，清算阶段扣减至零。详见授权与清算。
交易流水（Transaction）：授权是交易的前置环节，一笔流水可关联多个 authId，仅授权通过的交易才生成资金流转记录。

下一步

想先在沙盒里跑通一笔授权而不接卡组织？用沙盒·模拟交易的 POST /open-api/simulation/v1/fund-auth 触发一笔授权（请求参数 cardId/authType/amount/currency，返回 approved + errorCode）。
想了解授权之后资金如何清算？见授权与清算。
想配置 Webhook 与各类事件？见Webhook·配置。
拒绝原因与错误码对照，见授权拒绝与错误码。

​授权：把决策权交回您手里

​一笔授权的处理流程

​交易方向（direction）

​授权类型（authType）

​授权交易类型（transactionType）

​授权结果（responseCode）—— 接入机构的回应

​授权转发通知：安全交互规范（谁做什么）

​前置条件（接入机构）

​完整流程

​请求与响应结构

​请求头

​请求体

​encryptedData 解密后业务字段

​cardAcceptorNameLocation

Visa

Mastercard

​响应体

​授权请求体最小示例

​跟一笔授权走一遍

​与授权相关联的模块

​下一步

授权：把决策权交回您手里

一笔授权的处理流程

交易方向（direction）

授权类型（authType）

授权交易类型（transactionType）

授权结果（responseCode）—— 接入机构的回应

授权转发通知：安全交互规范（谁做什么）

前置条件（接入机构）

完整流程

请求与响应结构

请求头

请求体

`encryptedData` 解密后业务字段

`cardAcceptorNameLocation`

响应体

授权请求体最小示例

跟一笔授权走一遍

与授权相关联的模块

下一步