1. 账号与密钥 2. 签名算法 3. 提交卡密 4. 查询订单 5. 重提(重试) 6. 回调推送 7. 对账 8. 重试与补偿策略 9. 返回码总表 10. 收银台

卡密核销 · 下游对接文档

接口基址以我方下发为准 · JSON · UTF-8 · 三大机制:回调(结果推送)、重试(自动重投+人工重提)、对账(日切核对)

1. 账号与密钥

我方为每个下游开通渠道账号并分配一对密钥:

参数说明
key渠道 API KEY(公开标识,随请求上送)
secretAPI SECRET(仅本地计算签名,任何请求都不得携带)

所有接口都必须签名,提交记录自动归属到您的渠道名下;您只能查询/操作本人记录。若使用我方下发的全局兼容 KEY,提交还须额外携带 account 参数指定平台账号(见第 3 节)。

2. 签名算法

全部场景(您的请求、我方回调)使用同一公式:

  1. 取除 sign 外的全部参数,剔除值为空(""/null/未传)的参数;
  2. 按参数名 ASCII 码升序排列,拼成 k1=v1&k2=v2&…(使用原始值,非 URL 编码值);
  3. 末尾追加 &secret=SECRET,整串取 MD5(32 位小写)即为 sign。
场景SECRET 取值
您的接口请求您的 API SECRET
回调 —— 系统用户通道您的 API SECRET(与请求一致)
回调 —— 平台账号通道(如速兑卡 koncent)该渠道签名 KEY = 平台账号登录密码的 MD5 小写(我方后台可自定义,开通时告知)
// PHP(唯一公式,GET 回调验签时先将参数 URL 解码还原)
$params = $_POST;                       // 或 array_map('urldecode', $_GET)
$recv = $params['sign']; unset($params['sign']);
ksort($params);
$p = [];
foreach ($params as $k => $v) if ($v !== '' && $v !== null) $p[] = "$k=$v";
$expect = md5(implode('&', $p) . '&secret=' . $SECRET);   // $SECRET 按上表取值

// Node.js
function sign(p, secret) {
  const base = Object.keys(p).filter(k => k !== 'sign' && p[k] !== '' && p[k] != null)
    .sort().map(k => `${k}=${p[k]}`).join('&');
  return crypto.createHash('md5').update(base + '&secret=' + secret).digest('hex');
}

公共参数:key、ts(毫秒时间戳,请求签名偏差 >5 分钟拒签)、nonce(随机串,必填且 5 分钟内同一 KEY 下不得重复,重复返回 403「nonce 重复(疑似重放)」)、sign。

限流:按「密钥 + 来源 IP」滚动窗口计数,写操作(提交/重提)默认 60 次/分、读操作 300 次/分,超限返回 429,请退避排队重试。

3. 提交卡密 POST /api/submit

参数必填说明
key / ts / nonce / sign是签名公共参数
card_type_id是卡种 ID(见第 7 节卡类目录,如 311、306、100311、100306)
card_pwd是卡密;卡密前缀(卡头)用于判定卡种,与所选 card_type_id 不符时直接拦下;已在我方库核销成功、或已压在别的待核销订单里的卡密一律拒单(见 3.2)
card_no条件卡号;目录 iskami=0 的卡必填。利贞卡(311/100311)与元亨卡(306/100306)为双要素核销,卡号与卡密都不得为空
card_price是面值(元)。我方后台开启「卡面值校验」后,必须落在该卡种的在售面值档位内,否则 400 拒单(见 3.3)
req_no否下游订单号(≤32字符,幂等键;重复提交返回 409 并附原记录)
urgent否1=加急,默认 0
notify_url是本单结果回调地址(http(s))。API 提交必填,由下游随请求上送;本地页面提交可省略,省略时按渠道固定回调/全局兜底(见第 6 节)。默认仅公网可达地址,指向内网/保留网段返回 400;接收端在内网/专线时,由我方管理员为该渠道配置「回调 IP 白名单」,配置后本渠道只回调名单内地址
account条件平台账号名;仅当使用全局兼容 KEY 时必填(记录归属该渠道,回调按其密码MD5作SECRET验签)

利贞卡/元亨卡缺卡号或缺卡密时返回 { "code":400, "msg":"利贞卡/元亨卡需同时提供卡号和卡密" }:该单不入库、不向上游提交,补齐参数后用同一 req_no 重新提交即可。

3.1 卡密前缀(卡头)与卡种一致性

卡密前 4 位即卡头,可判定卡种:6337 开头=利贞卡、9503 开头=元亨卡(卡号头是制单日期,不能用来区分卡种)。提交的 card_type_id 与卡头不符时返回 { "code":400, "msg":"卡密以 6337 开头,属利贞卡,与所选元亨卡(card_type_id=306)不符" },同样不入库、不向上游提交;改用正确卡种后按原 req_no 重提即可。未登记的卡头一律放行(按您所选卡种提交),新卡段不会误杀;卡头规则表由我方后台维护,可扩展。

公开查询当前卡头规则:GET /api/pwd-rules → { "code":200, "data":[ { "prefix":"6337", "family":"利贞" }, { "prefix":"9503", "family":"元亨" } ] },可用于您侧自动校对/定位卡种。

3.2 卡密查重(防重复核销)

向上游提交之前,我方先以卡密查一遍自己的库(卡号头是制单日期,同批卡可能相同,故不作判重依据),命中即拒单,不入库、不消耗上游、也不进您的对账账单:

命中情况返回
该卡密已核销成功(含我方后台人工标记成功){ "code":400, "msg":"该卡密已核销成功(单号 DS20261114001),不能重复提交" }
该卡密正压在其它收银台订单的待核销队列(买家已贴、我方尚未上送){ "code":400, "msg":"该卡密已在待核销队列中(订单 P…),不能重复提交" }

msg 里的单号即最早那笔成功单,可据此核对是否同一张卡。用同一 req_no 重提原单不受影响(本单自身的记录会被排除,不会自撞);核销失败(fail/error)的卡密不拦,可继续重提或换卡重贴。判重跨渠道、跨提交方式(API 直连与收银台)全局生效。

3.3 卡面值档位校验(按开关生效)

我方后台可为每个卡种维护一组在售面值档位,并有一个总开关「提交时校验面值」。开关关闭时(默认)金额一律不校验,与历史口径一致;开启后:

场景返回后续动作
提交/下单金额不在该卡种在售档位内{ "code":400, "msg":"面值 95.00 元不在该卡种的在售面值内(在售档位:50.00 / 100.00 元),请用在售面值提交" }改成在售面值,用原 req_no 重提即可
该卡种还没配任何在售档位{ "code":400, "msg":"面值 100.00 元:该卡种还没有在售面值档位…后再提交" }联系我方在后台补齐档位
收银台下单未指定 card_type_id按全部在售卡种的面值并集判定;并集为空返回 400建议下单就带上 card_type_id

校验同时落在 API 直连提交(card_price)、收银台下单(amount)、买家贴卡与后台重提四条链路,口径一致;被拒的单同样不入库、不消耗上游、不进对账账单。金额按两位小数比对(100=100.00)。各卡种当前在售档位请以第 7.4 节目录或我方提供的价目表为准。

成功响应
{ "code":200, "msg":"核销提交成功",
  "data":{ "req_no":"DS20261114001", "status":"success", "platform_msg":"核销成功,金额100", "platform_order":"上游平台流水号", … } }

data.status:success 核销成功 / fail 平台拒绝 / error 系统异常。以 status=success 为最终成功依据;结果最终确定后我方会按第 6 节主动回调。platform_order 为我方向上游核销得到的平台流水号,提交即时可能为空,随核销受理/补单回填。

4. 查询订单 GET /api/query

签名公共参数+ req_no。提交超时/结果未知时,先查此接口再决定是否重提,防重复核销。

GET /api/query?key=…&ts=…&nonce=…&req_no=DS20261114001&sign=…
→ { "code":200, "data":{ "req_no":…, "status":"success", "platform_msg":…, "platform_order":"上游平台流水号", "callback_status":"ok", … } }
→ { "code":404, "msg":"记录不存在" } → { "code":403, "msg":"无权限查看该单号" }

5. 重提(人工重试) POST /api/resubmit

签名公共参数+ req_no。仅可对本人状态为 fail/error 的原单重新核销(原地更新,不产生新单号);已成功返回 400。全局兼容 KEY 重提时同样需带 account 且须与单号归属一致。

当前状态是否建议重提
error(系统异常/超时)可重提,建议先 /api/query 确认
fail + 明确业务拒绝(卡密无效/已核销/面额不符)不要重提,结果不会改变
success无需(返回 400)

6. 回调推送

核销结果最终确定后(含提交即失败、异常),我方主动推送至您的回调地址。回调地址由您在提交时通过 notify_url 上送(API 提交必填);未带的提交(仅限本地页面)按优先级回退:渠道固定回调 > 全局兜底地址。

6.1 提交方式(三选一,由我方按渠道配置)

方式请求形态
POST JSONContent-Type: application/json,body 即签名参数对象
GET 表单回调参数拼 URL:{notify_url}?card_price=…&card_type_id=…&…&sign=…,值 URL 编码、签名按原始值计算
GET 302 跳转同上(GET 拼参发起请求),您的接口返回 302 跳转至结果页,我方跟随重定向、以最终响应判定成功

携带 notify_url 的提交(即 API 提交的常态)一律按 POST JSON 推送至该地址;get/get302 仅用于渠道固定回调(页面提交兜底)场景。

出站地址安全策略:回调地址须为 http(s)、URL 内不得嵌账号密码,且解析结果必须为公网地址——环回、RFC1918 私网、运营商级 NAT(100.64/10)、链路本地与云厂商元数据(169.254.169.254)等一律拒绝(提交环节即 400)。投递时连接钉在已校验的 IP 上(HTTPS 仍按原域名校验证书),您的 302 跳转逐跳重新校验、最多 3 跳。请把接收端部署在公网可达地址。

6.2 回调参数

参数示例说明
req_noDS20261114001下游订单号(与提交一致)
statussuccesssuccess 核销成功 / fail 失败 / error 异常
code200平台返回码
msg核销成功,金额100结果描述(≤200字符)
card_type_id311卡种 ID
card_price100卡价
keykxxxx渠道标识(系统用户通道=API KEY;平台账号通道=渠道账号名)
ts1730000000000毫秒时间戳
noncea1b2c3d4随机串
sign32位小写MD5签名(见 2 节统一公式;SECRET 按渠道取值)

回调金额口径:card_price 就是您提交时的卡面值,我方不会在回调里乘结算折扣,报文里也不含 fee_rate / settle_amount 字段(加了会破坏您侧现有验签)。结算金额请以 7.1 /api/reconcile 的 settle_amount(=各成功单面值 × 该单提交时的费率快照)与我方后台计帐为准;您侧若要预估,用已知费率自乘,不要把回调金额直接当结算款。

6.3 您的响应要求(重要)

接收成功必须返回 HTTP 200 且响应体为字符串 success 或 JSON {"code":200}。返回其它内容(含 200 但报文不符)一律视为失败并将触发重试。

6.4 多次重试

核销结果确定后,我方会主动推送至回调地址;若推送失败或未收到您的成功应答(非 200 响应、响应体不符要求或超时 10 秒),将按 15 秒、1 分钟、5 分钟、30 分钟 的频率继续重发,最多重试 4 次(含首次共 5 次投递)。重试队列持久化存储,我方服务重启后会自动恢复补发未成功的回调(可能因此延迟或重复到达,请按幂等处理)。同一单号在重试期间若结果再次变化(如人工重提),旧重试队列自动作废、按最新结果重排。全部重试失败后不再推送,最终一致性请以查询/对账接口为准。

6.5 接收端要求

PHP 接收示例(POST JSON,SECRET=API SECRET)
$p = json_decode(file_get_contents('php://input'), true);
$recv = $p['sign']; unset($p['sign']);
ksort($p);
$base = http_build_query(array_filter($p, fn($v) => $v !== '' && $v !== null));
if (md5($base . '&secret=' . $SECRET) !== $recv) { http_response_code(400); exit('bad sign'); }
if ($p['status'] === 'success') { /* 按 req_no 幂等记账 */ }
echo 'success';

6.6 渠道回调配置(我方后台维护)

每个渠道一条回调配置,决定该渠道提交记录的结果推送方式。开通对接时请向我方管理员提供下列信息,变更后我方会以测试回调验证:

配置项说明
提交方式post(JSON)/ get(表单拼 URL)/ get302(跟随您返回的 302,以最终响应判定),按您接收端实现选定(见 6.1)
回调地址渠道固定回调地址(http(s)):仅作本地页面提交的兜底。API 提交一律以请求携带的 notify_url 为准(必填,见第 3 节)
签名KEY平台账号通道回调验签所用 SECRET:默认=该渠道平台账号登录密码的 MD5 小写,可自定义(开通时告知您实际值);系统用户通道直接用您的 API SECRET,无需此项
启用状态渠道回调开关。停用后我方不再向该渠道推送结果(回调状态记为未配置),请以 /api/query 轮询或对账兜底
测试回调我方管理员可用该渠道最近一笔提交记录立即发送一次真实形态的回调(按上方方式/地址/KEY 组包签名,不占用重试队列),收到 success 应答即配置验证通过
全局兜底地址平台级最后防线:当本单未带 notify_url、渠道也未配置固定回调时推送至此地址;正式上线前请勿依赖

7. 对账

7.1 日汇总 GET /api/reconcile

签名公共参数+ from(必须,YYYY-MM-DD)+ to(可选,默认=from,区间≤92天)。返回您渠道在区间内按提交日聚合的结果;req_no 重提为原地更新,计数只算一单。

GET /api/reconcile?key=…&ts=…&nonce=…&from=2026-11-14&sign=…
{ "code":200, "data":{
    "scope":"self", "from":"2026-11-14", "to":"2026-11-14",
    "total":120, "success_count":100, "success_amount":9800,
    "fee_rate":92.5, "settle_amount":9065, "settle_unrated_count":0,
    "fail_count":15, "error_count":5, "submit_amount":12000,
    "byType":[ { "card_type":"骏网利贞卡", "count":80, "success":70 }, … ] } }

结算字段:fee_rate 为您渠道当前结算费率(折,如 92.5 表示按面值 92.5% 结算);settle_amount 为各成功单按提交当时快照费率折算的结算金额之和,即我方应向您结算的金额;settle_unrated_count 为无费率快照的历史成功单数(未并入 settle_amount,需人工核对)。单条记录的快照费率见 /api/query、/api/records 的 fee_rate 字段;费率调整只影响之后的新单。

7.2 明细核对

用 GET /api/records(分页 ≤200)拉取当日明细逐单核对 req_no / status / card_price / fee_rate(结算金额=card_price × fee_rate ÷ 100);差异单用 /api/query 复核最终状态。

7.3 建议对账流程

  1. 每日 T+1(建议凌晨)拉取 from=昨日&to=昨日 汇总,与己方账务比对单数与成功金额;
  2. 不一致时拉明细定位差异单号;
  3. 回调未收到但 /api/query 显示 success 的单,补记账(以查询接口为准);
  4. 对账差异超过容忍度暂停对账并联系我方。

口径说明:按提交时间(北京时间)归属日期;成功金额=核销成功订单面值合计;fail/error 不计金额,可于重提成功后自动并入。

7.4 卡类目录

注意区分:目录里的 mianzhi 是上游平台在售面值;我方是否按面值拦单以「卡面值档位」配置为准(见 3.3),两者可能不同步,实际可提交的档位以我方下发的价目表为准。

GET /api/cards(公开):comments[].id 即 card_type_id,iskami(1=仅卡密,0=需卡号+卡密)、list[{mianzhi 面值, feilv 上游回收折扣, discount 参考价}](feilv 是上游平台给我方的折扣,与您渠道的结算费率 fee_rate 无关)、status(1=在售)。

8. 重试与补偿策略(下游侧)

我方已实现回调自动多次重试(6.4);您侧请按下表组合三种手段:自动重试提交、先查后重提、回调+对账补偿。

场景动作要点
提交请求超时/网络断开先 /api/query(req_no),有记录则视为结果已定;无记录再用原 req_no 重试提交原 req_no 重发命中幂等(409→附原记录),绝不产生重复核销
返回 502(error 已落库)间隔 ≥1 分钟后 /api/resubmit先 query 确认仍是 error
返回 fail(平台拒绝)不自动重提业务性失败(卡无效/已核销)重提无意义;人工核实后决定
返回 400(卡头与卡种不符,3.1)按正确 card_type_id 用原 req_no 重提该单未入库、未上送上游,改正即可,无重复核销风险
返回 400(该卡密已核销成功 / 已在待核销队列,3.2)不要重试同一张卡我方只核销一次;请核对是否重复下单或贴错卡
返回 400(面值不在在售档位,3.3)改成在售面值后用原 req_no 重提该单未入库、未上送上游;档位由我方维护,确需该面值请与我方确认
回调漏收/一直失败定时任务扫描己方“处理中”超 30 分钟的单,逐单 /api/query 补偿与 6.4 重试窗口对齐
每日兜底7.3 对账流程最终一致性的最后防线

重试纪律:① 同一单自动重试建议 ≤3 次且必须复用原 req_no;② ts 使用标准毫秒时间戳并保持服务器时钟同步(NTP),偏差 >5 分钟全部接口拒签;③ 收到 403 签名类错误先自查参数是否被二次编码/键名大小写变动,勿盲目重试。

9. 返回码总表

code含义下游处理建议
200请求成功(核销结果看 data.status)—
400参数缺失 / 利贞·元亨卡卡号或卡密为空 / 卡密卡头与所选卡种不符 / 非白名单卡种 / 面值或下单金额不在在售档位(见 3.3,我方开启校验时)/ notify_url 缺失、非法或指向内网保留网段 / 已成功单重提 / account 无效 / 收银台已关闭买家自选但未指定 card_type_id(见第 10 节)修正参数
401密钥未关联渠道,或全局 KEY 未带 account联系我方开通
403签名错误 / key 无效 / ts 过期 / nonce 重复(疑似重放) / 密钥所属账号已被我方停用 / 越权查单检查签名、服务器时钟与 nonce 随机性;停用需我方管理员恢复
404单号不存在核对 req_no
409req_no 重复(幂等保护,返回原记录)用 /api/query 确认原单结果
502上游平台异常(已落库为 error,可稍后重提)先查单再决定重提
429触发限流(默认写 60 次/分、读 300 次/分,按密钥+来源 IP 计)退避排队重试,勿并发放大

10. 收银台(托管收款) POST /api/pay/create

买家自己去看淘宝买卡、再把卡密贴回我方收银台页面,由我方核销并回传结果。与第 3 节的区别:卡密只经过我方页面,不经过您的服务器。

  1. 您的服务端调 POST /api/pay/create(金额 + 可选卡种 + notify_url)拿到 pay_url;
  2. 把 pay_url 给买家(跳转或二维码)。收银台是手机版优先的页面(手机打开即用,桌面浏览器同样可用),显示应付金额、剩余时间与该卡种的淘宝搜索链接,买家点开购买;口令失效或没抄全时买家看到整屏「收银台链接已失效」提示页(不泄露该单任何信息),请重新下单取新链接,勿复用旧链接;
  3. 买家回到收银台整段粘贴卡号卡密(「卡号:… 密码:…」「卡号 卡密」、分行、全角都能自动拆分,并按卡密卡头识别卡种);manual 口径下提交后输入区即置为只读,重复提交不会覆盖已提交的卡密,换卡请联络我方;
  4. 核销由谁触发取决于下单的 mode:manual(默认)=买家提交后进入「核销中」,由我方后台核销后才有结果;auto=买家提交即向上游核销,当场出结果;
  5. 成功 → 页面提示支付成功并按 return_url 回跳您站;失败 → 显示原因,可换卡重贴;
  6. 结果同时按第 6 节回调规则推送(req_no 即 order_no),成功失败都推;也可主动查 GET /api/pay/query。
下单参数必填说明
key / ts / nonce / sign是签名公式同第 2 节;全局 KEY 须额外带 account 指定渠道
amount是需核销的卡面值(元,正数、最多两位小数)。核销金额固定取此值,页面上送的任何金额一律忽略;我方开启「卡面值校验」后须落在在售档位内(见 3.3)
notify_url是本单结果回调地址;内网/专线接收端需我方先给该渠道配回调 IP 白名单
card_type_id条件指定卡种(见 7.4 目录)。我方开启「允许买家自选卡种」时可不传,买家在收银台点选;我方关闭该开关后必填,不传返回 400(我方收银台已关闭「买家自选卡种」,下单必须指定 card_type_id…),且买家页面上送的卡种一律忽略。建议对接时固定传本渠道在售的卡种
out_trade_no否您侧订单号,同渠道唯一;重复上送幂等返回原单(duplicated:true)
order_no否自定义我方单号(字母数字下划线 6~64 位),默认系统生成 P 开头
return_url否支付完成后买家浏览器回跳地址,仅 http(s)、不允许带账号密码
mode否manual(默认)=买家提交后由我方后台核销;auto=买家提交即核销。不传按我方全局口径
data.state含义您侧处理
waiting买家尚未贴卡密继续等待,未完成
redeeming买家已贴卡密,等我方核销(manual 口径的中间态)继续等待,尚不算完成
done核销成功=支付成功按 data.submit 发货/记账
failed卡密被上游拒绝提示买家换卡重贴,仍算未完成
closed超时未付 / 贴卡次数用尽 / 我方关闭视为支付失败,可重新下单

时效与次数:订单默认 4 小时有效、贴卡密默认最多 12 次(我方可按渠道调整);已进入 redeeming 的单不受有效期影响,卡号卡密只在收银台与我方后台之间流转,/api/pay/query 与回调报文都不返回。结算口径与第 3 节直连提交完全一致——同一套费率快照、对账与回调重试,您侧无需区分来源。

收银台链接里的一次性口令等同该单的取款凭证:请勿公开传播、勿写进日志、勿放到第三方页面。/api/pay/* 与其他签名接口共用同一限流与重放保护,nonce 每单都要换新。

对接联调、配置/变更回调方式与地址、设置签名KEY、更换密钥请联系我方管理员(对应后台「回调设置」各渠道配置项,见 6.6)。请勿将 secret 写入前端页面或客户端代码。