鉴权指南 - DCS Technical Documentation

无论您是交易所、钱包还是平台方，只要拿到 DCS 交付的一对密钥，就可以用一套统一的签名规则调用所有 DeCard 托管 接口——本页帮您把鉴权一次配通。作为持牌、自有 BIN 的发卡机构，DCS 对每一次接口调用都要求可验证的来源与防重放保护。

该模型为每个用户维护独立的法币/数币账户与余额，不涉及链上抵押品。

本组概览

本组汇总了您从接入开发到生产上线所需的技术配置与安全凭据：

子页	用途
鉴权指南（本页）	API Key / Secret Key 管理与接口 HMAC-SHA256 签名
IP 白名单	向 DCS 报备您的网络出口地址，用于接口调用放行与生产凭证安全提取
SessionId 加密与公钥配置	DeCard 托管模式实际具备的加密与签名能力汇总
H5 KYC 与开卡引导页	嵌入式 KYC 与开卡引导 H5 流程
Web SDK 接入	前端集成 SDK
Webhook 与 WebSocket 实时通知	事件回调（Webhook）与 WebSocket 实时推送（DeCard 托管特色）

1. 密钥与请求头

您会从 DCS 拿到什么

字段	描述	谁提供
`apiKey`	调用接口的全局唯一标识，用于身份识别与请求来源追踪	DCS
`secretKey`	用于计算请求签名的密钥，请妥善保管，切勿泄露给任何第三方	DCS

apiKey 是一个全局唯一标识，方便身份识别与数据分析；为防止他人冒用您的 apiKey 发起请求，需配对 secretKey 按约定规则生成签名，并随请求一并提交给 DCS 验证。DCS 会通过安全渠道向您交付这对密钥，接入机构对接口的任何调用都应遵循约定的签名协议。

沙盒环境的 apiKey/secretKey 请联系 DCS 团队获取；生产环境必须走生产环境密钥的安全提取。

每个请求必带的头

接入机构对接口的每次调用，都需在 HTTP 头中携带以下各头：

Header	必填	说明
`Content-Type`	REQUIRED	请求体为 JSON 时固定 `application/json`。缺失时返回 HTTP 400，业务码 `SYS_ILLEGAL_PARAM`
`X-DAPI-API-KEY`	REQUIRED	DCS 交付的 `apiKey`
`X-DAPI-TIMESTAMP`	REQUIRED	请求时间戳（毫秒），用于防重放
`X-DAPI-NONCE`	REQUIRED	随机数，取值范围 `[10000, 99999]`，保证请求一次性有效
`X-DAPI-SIGN`	REQUIRED	按下文规则计算的 HMAC-SHA256 签名（十六进制小写）

secretKey 仅用于本地计算签名，切勿在请求头中明文传输。

缺少 Content-Type: application/json 的典型响应：

{"code":"SYS_ILLEGAL_PARAM","message":"illegal param","messageDetail":null,"data":null,"success":false}

该 success=false 来自 Content-Type 缺失时的框架级错误响应，不代表所有业务响应都稳定包含 success。正常集成仍应以 code 判断成败，不要依赖 success 字段。

2. 接口签名（HMAC-SHA256）

签名规则

使用 HmacSHA256 算法，以 secretKey 为密钥，对拼接串签名：

X-DAPI-SIGN = HmacSHA256( apiKey + timestamp + nonce + payload , secretKey )

输出为十六进制小写字符串。 拼接串各段说明：

段	取值
`apiKey`	与 `X-DAPI-API-KEY` 一致
`timestamp`	与 `X-DAPI-TIMESTAMP` 一致（毫秒时间戳）
`nonce`	与 `X-DAPI-NONCE` 一致
`payload`	GET 请求：URL 编码后的查询参数（query string）；其他方法：原始请求体（body）

if method is GET:
    payload = url.encodedQuery()     // 例如 externalUserId=<externalUserId>&cardMantissa=1670
else:
    payload = body                   // 原始 JSON 请求体字符串

签名算法固定为 HmacSHA256，请一律使用该算法。

防重放（谁做：DCS 校验 / 接入机构生成）

TIMESTAMP：取值为 13 位毫秒级时间戳（如 Date.now()，非 10 位秒级）。格式不对会返回 DAPI_TIMESTAMP_FORMAT_ERROR。DCS 只处理有效期 5 秒内的请求，超出即返回 DAPI_TIMESTAMP_EXPIRED——请用当前时间重新生成并重算签名，并确保本地时钟同步。
NONCE：每次请求生成一个 [10000, 99999] 的随机数，保证请求一次性有效，请勿复用。

鉴权失败时，请先检查时间戳、nonce 和签名原文；具体错误码以接口实际返回及 DCS 针对本产品提供的字典为准。

签名实现示例

JavaScript（Postman Pre-request Script）

const CryptoJS = require('crypto-js');

const apiSecret = '<your-secret-key>';
const apiKey    = '<your-api-key>';

// GET 用查询参数；其他方法用请求体，二选一拼接
const queryParams  = '<your-query-param>';   // 例如 externalUserId=<externalUserId>&cardMantissa=1670
const requestBody  = '<your-request-body>';  // POST/PUT 时的原始 body
const nonce        = 10010;
const timestamp    = Date.now().toString();

const dataToSign = apiKey + timestamp + nonce + queryParams + requestBody;
const signature  = CryptoJS.HmacSHA256(dataToSign, apiSecret).toString(CryptoJS.enc.Hex);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;

public final class HmacSignature {
    private static final String HMAC_SHA256 = "HmacSHA256";

    public static String getSignature(String apiSecret, String data) throws Exception {
        SecretKeySpec keySpec = new SecretKeySpec(apiSecret.getBytes(), HMAC_SHA256);
        Mac mac = Mac.getInstance(HMAC_SHA256);
        mac.init(keySpec);
        byte[] hmac = mac.doFinal(data.getBytes());
        return Hex.encodeHexString(hmac);
    }
}

完整请求示例（GET）

curl --location 'https://{domain}/card/v2/detail?externalUserId=<externalUserId>&cardId=<cardId>' \
  --header 'Content-Type: application/json' \
  --header 'X-DAPI-API-KEY: <your-api-key>' \
  --header 'X-DAPI-SIGN: <calculated-signature>' \
  --header 'X-DAPI-TIMESTAMP: <millis-timestamp>' \
  --header 'X-DAPI-NONCE: <random-10000-99999>'

此例中 payload = externalUserId=<externalUserId>&cardId=<cardId>（GET 的查询参数）。验证您的实现时，先用 DCS 提供的同一组 apiKey/timestamp/nonce/payload 复算出相同的 X-DAPI-SIGN，再上线。

示例中所有 externalUserId、apiKey、X-DAPI-SIGN、TIMESTAMP、NONCE 均为占位符，请勿当作真实值；DeCard 托管模式涉及大量终端用户隐私数据，调试日志同样不应记录真实凭据与 PII。

统一响应结构

所有接口返回统一结构：

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": {
    "message": "",
    "title": "",
    "type": "",
    "icon": "",
    "action": "",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": ""
}

字段	类型	说明
`code`	string	业务状态码，成功为 `SYS_SUCCESS`；失败为具体错误码
`message`	string	简要信息，成功时通常为空
`messageDetail`	object	结构化展示对象，含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`，可用于前端引导展示；成功时各字段通常为空。请勿据此判断成败，业务成败一律以 `code` 为准
`data`	object	业务数据

判断成功请以 code == "SYS_SUCCESS" 为准。响应结构不含 success 布尔字段，请勿依赖该字段。

3. 生产环境密钥的安全提取

为避免生产环境的 apiKey/secretKey 在交付途中泄露，生产密钥不直接发给您，而是走一次性安全提取流程。

沙盒环境无需此流程，直接联系 DCS 团队获取即可。

流程（谁做）

接入机构提供：一个安全邮箱地址 + 一个用于提取的请求 IP。
- 邮箱用于接收提取指引；该 IP 会被加入「提取密钥」白名单。
DCS 发送：安全邮箱收到一封邮件，内含一个仅一次有效的临时安全链接。
接入机构提取：把 extractUrl 与 extractSecretKey 拼接后，在指定 IP 的机器上执行，即可领取 apiKey/secretKey。

邮件中的字段

字段	类型	描述
`expireTime`	string	提取安全码的有效期
`extractSecretKey`	string	密钥提取安全码
`extractUrl`	string	密钥提取 URL
`howToUse`	string	使用方式说明
`notes`	string	提示：链接仅可提取一次

成功响应

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "expireTime": "2024-10-21T16:52+08:00[Asia/Shanghai]",
    "extractSecretKey": "<one-time-extract-secret>",
    "extractUrl": "https://{domain}/internal/open-api/v1/secret-extract/",
    "howToUse": "Please concatenate the url with the secret-key and execute it on the specified machine.",
    "notes": "This link is only valid for one AKSK extraction, if the content is not properly accessed, the AKSK may have been compromised, please contact us promptly."
  }
}

失败响应

{
  "code": "ERROR-CODE",
  "message": "simple describe, see error-code list",
  "messageDetail": null,
  "data": null
}

此处仅展示失败响应结构。具体错误码请以接口实际返回及 DCS 针对本产品提供的字典为准，本版不引用其他产品的错误码表。

若未能成功领取密钥：说明链接可能已在有效期内被使用、密钥存在泄露风险。请立即联系 DCS 商务，重新走邮件流程换发。该提取 IP 与日常接口调用 IP 可以不同，请分别向 DCS 说明用途；IP 白名单的提交方式见 IP 白名单。

下一步 / 相关

鉴权配通后，前往快速开始跑通第一张卡，或先在前置准备确认开通与回调已就绪。其他接入资源：

IP 白名单：向 DCS 报备您的网络出口地址，用于接口调用放行与生产凭证安全提取。
SessionId 加密与公钥配置：DeCard 托管模式实际具备的加密与签名能力汇总。
H5 KYC 与开卡引导页：嵌入式 KYC 与开卡引导流程。
Web SDK 接入：前端集成 SDK。
Webhook 与 WebSocket 实时通知：事件回调（Webhook）与 WebSocket 实时推送（DeCard 托管特色）。

​本组概览

​1. 密钥与请求头

​您会从 DCS 拿到什么

​每个请求必带的头

​2. 接口签名（HMAC-SHA256）

​签名规则

​防重放（谁做：DCS 校验 / 接入机构生成）

​签名实现示例

​完整请求示例（GET）

​统一响应结构

​3. 生产环境密钥的安全提取

​流程（谁做）

​邮件中的字段

​下一步 / 相关

本组概览

1. 密钥与请求头

您会从 DCS 拿到什么

每个请求必带的头

2. 接口签名（HMAC-SHA256）

签名规则

防重放（谁做：DCS 校验 / 接入机构生成）

签名实现示例

完整请求示例（GET）

统一响应结构

3. 生产环境密钥的安全提取

流程（谁做）

邮件中的字段

下一步 / 相关