卡序 开发者文档 返回管理后台
CARD DESK / API V1

把收卡流程接入你的业务

通过商户接口创建订单,获取独立提交链接。客户提交卡密后进入人工审核,审核结果通过签名回调通知你的系统。

当前协议 · 自定义 HMAC-SHA256 接口

此文档描述卡序当前实现的接口,并不代表兼容其他平台的协议。外部商户接入前,请确保服务地址已开放外部访问,并使用正式商户密钥。

01创建商户获取商户号与密钥
02API 创建订单返回客户提交链接
03客户提交卡密进入人工审核
04接收结果回调更新你的订单状态

请求签名

所有商户 API 请求都需要以下请求头。密钥仅应保存在商户服务端,不能放入客户页面、App 前端代码或 URL。

请求头格式说明
X-Merchant-Id字符串管理后台生成的商户号。
X-TimestampUnix 秒与服务器当前时间相差不超过 5 分钟。
X-Nonce16–80 个字符每次请求随机生成,仅限字母、数字、下划线、连字符;不可重复使用。
X-Signature64 位小写 hex以商户密钥计算 HMAC-SHA256。
签名原文(字段间用换行符连接)
timestamp + '\n' + nonce + '\n' + HTTP_METHOD + '\n' + pathname + '\n' + rawBody
  • HTTP_METHOD 使用大写,例如 POST、GET。
  • pathname 是请求 URL 的路径部分,不含域名或查询参数。
  • rawBody 是实际发送的原始 UTF-8 请求正文,GET 使用空字符串。
  • 每商户限流为每分钟 60 次请求。网络重试时保留商户订单号,但重新生成时间戳、nonce 和签名。

创建订单

POST/api/v1/orders

请求类型为 application/json。创建成功后,将返回的 submitUrl 提供给客户。提交链接默认有效期为 30 分钟。

字段要求说明
merchantOrderNo必填字符串商户系统中的订单号,在同一商户下唯一。
amount必填字符串订单金额,以元为单位,使用两位小数,如 "50.00"。
productName可选字符串显示在客户提交页面的商品名称。
Node.js · 创建订单
import { createHmac, randomBytes } from 'node:crypto';

const baseUrl = process.env.CARD_API_BASE_URL;
const merchantId = process.env.CARD_MERCHANT_ID;
const secret = process.env.CARD_MERCHANT_SECRET;

const path = '/api/v1/orders';
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
// 用于签名和发送的 JSON 字节必须一致。
const body = JSON.stringify({
  merchantOrderNo: 'SHOP-20261116-0001',
  amount: '50.00',
  productName: '苹果充值卡'
});
const message = [timestamp, nonce, 'POST', path, body].join('\n');
const signature = createHmac('sha256', secret)
  .update(message, 'utf8').digest('hex');

const response = await fetch(new URL(path, baseUrl), {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Merchant-Id': merchantId,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature
  },
  body
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
// 将 result.data.submitUrl 展示给客户或引导客户打开。
console.log(result.data.id, result.data.status);
成功响应 · 关键字段
{
  "data": {
    "id": "系统生成的订单号",
    "merchantOrderNo": "SHOP-20261116-0001",
    "amount": "50.00",
    "status": "awaiting_card",
    "submitUrl": "https://你的服务域名/card-submit/订单号/随机令牌",
    "expiresAt": 1794819600000
  }
}

创建订单支持幂等。同一商户订单号和相同参数再次请求时返回原订单;如果订单号相同但参数不同,返回 HTTP 409,避免重复下单或改变金额。

查询订单

GET/api/v1/orders/{merchantOrderNo}

使用创建订单时传入的商户订单号查询。只能读取当前签名商户自己的订单。请求仍需签名,正文留空;返回 data 中的订单记录。

Node.js · 查询订单(复用创建示例中的变量)
const merchantOrderNo = 'SHOP-20261116-0001';
const path = '/api/v1/orders/' + encodeURIComponent(merchantOrderNo);
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const message = [timestamp, nonce, 'GET', path, ''].join('\n');
const signature = createHmac('sha256', secret)
  .update(message, 'utf8').digest('hex');
const response = await fetch(new URL(path, baseUrl), {
  headers: {
    'X-Merchant-Id': merchantId,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature
  }
});

订单状态

状态值含义何时产生
awaiting_card等待提交订单创建成功,客户尚未提交卡密。
pending_review等待人工审核卡密已收到,尚未确认成功或失败。
succeeded审核通过管理员人工确认成功,触发结果回调。
failed审核未通过管理员人工确认失败,触发结果回调。
expired提交超时有效期结束前未提交卡密。

已进入 pending_review 的订单,不会因为原提交链接到期而取消审核。请将“卡密已收到”和“人工审核通过”作为两个不同状态处理。

结果回调

在管理后台创建商户时设置固定的 HTTPS 回调地址。地址不能使用 IP、本地域名或查询参数。只有人工审核为成功或失败的真实订单才会触发回调;后台创建的测试订单不会向外部发送通知。

POST · 回调 JSON 正文
{
  "eventId": "系统订单号:succeeded",
  "orderId": "系统订单号",
  "merchantOrderNo": "SHOP-20261116-0001",
  "amount": "50.00",
  "status": "succeeded",
  "reviewedAt": 1794819000000
}

回调携带与商户请求相同的四个签名头,使用相同的签名规则及商户密钥。reviewedAt 为毫秒时间戳;status 仅为 succeeded 或 failed。回调不包含卡密或内部审核备注。

服务端验签与应答步骤
// 先保留收到的原始 body;不要先 JSON.parse 再序列化验签。
const rawBody = await request.text();
const timestamp = request.headers.get('X-Timestamp');
const nonce = request.headers.get('X-Nonce');
const signature = request.headers.get('X-Signature');
const path = new URL(request.url).pathname;
const message = [timestamp, nonce, 'POST', path, rawBody].join('\n');
const expected = createHmac('sha256', merchantSecret)
  .update(message, 'utf8').digest('hex');

// 验证商户号、时间窗口、nonce 和签名;使用恒定时间比较。
// 验签通过后,以 eventId 做幂等键,事务更新你自己的订单。
// 必须比对订单号和金额,不要仅凭浏览器跳转确认订单成功。
// 业务处理成功后才应答:HTTP 200,纯文本 success。

你的接口必须返回 HTTP 2xx,并且响应正文为纯文本 success(大小写敏感,忽略首尾空格),平台才会将本次通知标记为已送达。

  • 接收方应以 eventId 做幂等处理,并核对商户订单号、金额与本地订单。
  • 回调重试使用相同 eventId,但会生成新的 nonce 和签名。
  • 回调失败保留在后台,管理员可以手动重试;当前版本没有定时自动重试。
  • 订单状态和回调状态相互独立,回调失败不会撤销已经完成的人工审核。
  • 提交页面的展示结果不能代替服务端验签;可用查询接口辅助核对最终状态。

错误与重试

错误响应
{
  "error": {
    "code": "错误类型",
    "message": "可读的错误说明"
  }
}

客户端应先检查 HTTP 状态码,再读取错误详情。常见问题包括缺少参数、签名无效或超时、重复 nonce、重复订单参数冲突、订单不存在,以及请求频率超限。

创建订单遇到网络中断时,可以使用相同的商户订单号和参数重试,或先查询该订单。每次重试都使用新的 nonce 和签名。请勿在排查日志中记录商户密钥、客户卡密或包含完整令牌的提交链接。