鉴权指南 - DCS Technical Documentation

📄 正文

无论您是交易所、钱包还是平台方，只要拿到 DCS 交付的一对密钥，就可以用一套统一的签名规则调用所有 /open-api/ 接口——本页帮您把鉴权一次配通。作为持牌、自有 BIN 的发卡机构，DCS 对每一次接口调用都要求可验证的来源与防重放保护。本页覆盖三件事：调用接口的 HMAC 签名、生产环境密钥的安全提取、以及授权通知所用的 RSA 公钥生成。

1. 密钥与请求头

您会从 DCS 拿到什么

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

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

每个请求必带的头

接入机构对 /open-api/ 的每次调用，都需在 HTTP 头中携带（请求体为 JSON 时还需带 Content-Type: application/json，官网示例未列出，但缺失会导致 415 错误）：

Header	必填	说明
`Content-Type`	REQUIRED	固定 `application/json`。JSON 请求体必须携带该头，否则后端返回 `415 Unsupported Media Type`——这是接入初期最常见的一类失败
`X-DAPI-API-KEY`	REQUIRED	DCS 交付的 `apiKey`
`X-DAPI-TIMESTAMP`	REQUIRED	请求时间戳（Unix 毫秒时间戳，与时区无关），用于防重放
`X-DAPI-NONCE`	REQUIRED	随机数，取值范围 `[10000, 99999]`；每次请求都应重新生成
`X-DAPI-SIGN`	REQUIRED	按下文规则计算的 HMAC-SHA256 签名（十六进制小写）

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

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()     // 例如 cardOrderRef=14
else:
    payload = body                   // 原始 JSON 请求体字符串

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

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

TIMESTAMP：DCS 默认只接受 5 秒内 的请求；超时请求一律拒绝。接入机构请确保本地时钟与 UTC 同步。
NONCE：每次请求生成一个 [10000, 99999] 的随机数，请勿复用。接入机构仍需为业务写操作设置幂等键，并避免在 5 秒窗口内重放完全相同的请求。

签名实现示例

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}';   // 例如 cardOrderRef=14
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}/open-api/card-order/v1/detail?cardOrderRef=14' \
  --header 'Content-Type: application/json' \
  --header 'X-DAPI-API-KEY: 697EA72DACF742F280943DAB211E6C2B' \
  --header 'X-DAPI-TIMESTAMP: 1743044911331' \
  --header 'X-DAPI-NONCE: 10100' \
  --header 'X-DAPI-SIGN: b979d2ea5c70187ddac7d7a5937c40c87a58f765594b740e596d25fca96f2dcb'

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

统一响应结构

所有 /open-api/ 接口返回统一结构：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": { }
}

字段	说明
`code`	业务状态码，成功为 `SYS_SUCCESS`；失败为具体错误码（见错误码页）
`message`	简要信息，成功时通常为 `null`
`messageDetail`	详细信息对象，通常为 `null`
`data`	业务数据

判断成功请以 code == "SYS_SUCCESS" 为准；失败时 code 为具体错误码（见错误码页）。

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": "4f72b1e9c49e4ac1bbc2cd12b5e44993",
    "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 商务，重新走邮件流程换发。

4. RSA 公钥（授权通知专用）

授权转发通知（DCS → 接入机构 auth_url）对敏感数据（如交易金额、币种）采用 RSA-2048 双向签名 + 加密，与上文调用接口用的 HMAC 是两套独立机制。授权通知没有额外的 AES/IV 层：业务字段整体以 RSA 分段加密，签名算法为 SHA256withRSA。

HMAC：接入机构调用 /open-api/ 接口时使用（本页第 1–2 节）。
RSA：DCS 向接入机构推送授权通知时使用，保护授权流程上的敏感字段。

接入机构需自行生成一对 RSA 密钥，把公钥（external_public_key）交给 DCS，私钥自己保管。

生成方式（谁做：接入机构）

# 1. 生成 2048 位 RSA 私钥
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# 2. 从私钥导出公钥
openssl rsa -pubout -in private_key.pem -out public_key.pem

# 3. 去掉头尾标记与换行，得到提交给 DCS 的单行公钥串
cat public_key.pem | sed '/BEGIN/d; /END/d' | tr -d '\n'

第 3 步输出的单行字符串即 external_public_key，连同 auth_url 一并提供给 DCS。

DCS RSA 公钥（谁给：DCS）

接入机构验证 DCS 通知签名、加密返回数据时，使用 DCS 的 RSA 公钥。

沙盒环境：

生产环境：请联系 DCS 团队获取。

加解密与签名 Java 示例

签名算法为 SHA256withRSA，密钥 2048 位，加解密按块分段（加密块 245 字节 / 解密块 256 字节）：

import javax.crypto.Cipher;
import java.io.ByteArrayOutputStream;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class RSAUtil {
    private static final String ALGORITHM = "RSA";
    private static final int KEY_SIZE = 2048;
    private static final int MAX_ENCRYPT_BLOCK = KEY_SIZE / 8 - 11; // 245
    private static final int MAX_DECRYPT_BLOCK = KEY_SIZE / 8;      // 256

    // 公钥加密（分段）
    public static String encrypt(String data, PublicKey publicKey) throws Exception {
        Cipher cipher = Cipher.getInstance(ALGORITHM);
        cipher.init(Cipher.ENCRYPT_MODE, publicKey);
        byte[] encryptedBytes = doSegment(cipher, data.getBytes(), MAX_ENCRYPT_BLOCK);
        return Base64.getEncoder().encodeToString(encryptedBytes);
    }

    // 私钥解密（分段）
    public static String decrypt(String encryptedData, PrivateKey privateKey) throws Exception {
        byte[] dataBytes = Base64.getDecoder().decode(encryptedData);
        Cipher cipher = Cipher.getInstance(ALGORITHM);
        cipher.init(Cipher.DECRYPT_MODE, privateKey);
        byte[] decryptedBytes = doSegment(cipher, dataBytes, MAX_DECRYPT_BLOCK);
        return new String(decryptedBytes);
    }

    // 从 Base64 字符串还原公钥
    public static PublicKey parsePublicKey(String base64PublicKey) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(base64PublicKey);
        return KeyFactory.getInstance(ALGORITHM).generatePublic(new X509EncodedKeySpec(keyBytes));
    }

    // 从 Base64 字符串还原私钥
    public static PrivateKey parsePrivateKey(String base64PrivateKey) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(base64PrivateKey);
        return KeyFactory.getInstance(ALGORITHM).generatePrivate(new PKCS8EncodedKeySpec(keyBytes));
    }

    // 私钥签名（SHA256withRSA）
    public static String sign(String data, PrivateKey privateKey) throws Exception {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);
        signature.update(data.getBytes());
        return Base64.getEncoder().encodeToString(signature.sign());
    }

    // 公钥验签
    public static boolean verify(String data, String sign, PublicKey publicKey) throws Exception {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initVerify(publicKey);
        signature.update(data.getBytes());
        return signature.verify(Base64.getDecoder().decode(sign));
    }

    private static byte[] doSegment(Cipher cipher, byte[] data, int maxBlock) throws Exception {
        int inputLen = data.length;
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offset = 0;
        while (offset < inputLen) {
            int blockLen = Math.min(inputLen - offset, maxBlock);
            out.write(cipher.doFinal(data, offset, blockLen));
            offset += blockLen;
        }
        return out.toByteArray();
    }
}

授权通知的完整加解密与验签细节见授权转发与加密。

5. IP 白名单（三类，缺一不可）

DCS 对所有交互均设白名单。接入机构需向 DCS 提供沙盒与生产各自的静态出口 IP，分别用于以下三个方向：

白名单	方向	用途	谁提供
接口调用白名单	接入机构 → DCS	调用 `/open-api/` 接口的网络出口地址	接入机构
Webhook 白名单	DCS → 接入机构 `webhook_url`	接收卡订单/交易等事件通知的出口地址	接入机构
授权转发白名单	DCS → 接入机构 `auth_url`	接收授权转发通知请求的出口地址	接入机构

沙盒与生产环境分别配置，请勿混用。生产密钥的「提取 IP」（第 3 节）与「接口调用 IP」可以不同，请分别向 DCS 说明用途。

下一步

鉴权配通后，前往快速开始跑通第一张卡，或先在前置准备确认开通、回调与白名单已就绪。授权通知的 RSA 加解密细节见授权转发与加密。

​📄 正文

​1. 密钥与请求头

​您会从 DCS 拿到什么

​每个请求必带的头

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

​签名规则

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

​签名实现示例

​完整请求示例（GET）

​统一响应结构

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

​流程（谁做）

​邮件中的字段

​4. RSA 公钥（授权通知专用）

​生成方式（谁做：接入机构）

​DCS RSA 公钥（谁给：DCS）

​加解密与签名 Java 示例

​5. IP 白名单（三类，缺一不可）

​下一步

📄 正文

1. 密钥与请求头

您会从 DCS 拿到什么

每个请求必带的头

2. 接口签名（HMAC-SHA256）

签名规则

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

签名实现示例

完整请求示例（GET）

统一响应结构

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

流程（谁做）

邮件中的字段

4. RSA 公钥（授权通知专用）

生成方式（谁做：接入机构）

DCS RSA 公钥（谁给：DCS）

加解密与签名 Java 示例

5. IP 白名单（三类，缺一不可）

下一步