把收卡流程接入你的业务
通过商户接口创建订单,获取独立提交链接。客户提交卡密后进入人工审核,审核结果通过签名回调通知你的系统。
此文档描述卡序当前实现的接口,并不代表兼容其他平台的协议。外部商户接入前,请确保服务地址已开放外部访问,并使用正式商户密钥。
请求签名
所有商户 API 请求都需要以下请求头。密钥仅应保存在商户服务端,不能放入客户页面、App 前端代码或 URL。
| 请求头 | 格式 | 说明 |
|---|---|---|
X-Merchant-Id | 字符串 | 管理后台生成的商户号。 |
X-Timestamp | Unix 秒 | 与服务器当前时间相差不超过 5 分钟。 |
X-Nonce | 16–80 个字符 | 每次请求随机生成,仅限字母、数字、下划线、连字符;不可重复使用。 |
X-Signature | 64 位小写 hex | 以商户密钥计算 HMAC-SHA256。 |
timestamp + '\n' + nonce + '\n' + HTTP_METHOD + '\n' + pathname + '\n' + rawBodyHTTP_METHOD使用大写,例如POST、GET。pathname是请求 URL 的路径部分,不含域名或查询参数。rawBody是实际发送的原始 UTF-8 请求正文,GET 使用空字符串。- 每商户限流为每分钟 60 次请求。网络重试时保留商户订单号,但重新生成时间戳、nonce 和签名。
创建订单
/api/v1/orders请求类型为 application/json。创建成功后,将返回的 submitUrl 提供给客户。提交链接默认有效期为 30 分钟。
| 字段 | 要求 | 说明 |
|---|---|---|
merchantOrderNo | 必填字符串 | 商户系统中的订单号,在同一商户下唯一。 |
amount | 必填字符串 | 订单金额,以元为单位,使用两位小数,如 "50.00"。 |
productName | 可选字符串 | 显示在客户提交页面的商品名称。 |
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,避免重复下单或改变金额。
查询订单
/api/v1/orders/{merchantOrderNo}使用创建订单时传入的商户订单号查询。只能读取当前签名商户自己的订单。请求仍需签名,正文留空;返回 data 中的订单记录。
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、本地域名或查询参数。只有人工审核为成功或失败的真实订单才会触发回调;后台创建的测试订单不会向外部发送通知。
{
"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 和签名。请勿在排查日志中记录商户密钥、客户卡密或包含完整令牌的提交链接。