中金支付 · 开发接口

快速开始：按这个顺序对接

商户只对接千词支付的 JSON 接口，不直接调用中金 XML 接口，也不需要在商户系统保存中金证书。本文示例中 YOUR_*、merchant.example.com 等都是占位内容，不是实际账号、单号或可用地址。

1. 复制 Node.js 18 示例，只调用一次 /banks，先验证公网连接、AppId 和签名。
2. 选借记卡传 DEBIT_CARD（默认）；选贷记卡传 CREDIT_CARD。贷记卡不是全部不支持，但必须单独开通且只能使用银行一键方式。 两类银行名单可能不同，以本商户本次查询结果为准。
3. 发起 /bindcard，引导持卡人打开 redirect_url；只有查询/通知确认 bound 后才能扣款。不要用浏览器回跳判断成功。
4. 用该中金 bind_id 发起 /pay。保存 out_trade_no、trade_no；已明确成功/失败可同步处理，paying 或超时则查询原单。
5. 需要退本金时发起一次全额 /refund；需要撤销银行签约时调用 /unbind。退款不等于解绑，解绑也不会退款。
6. 联调验收回调签名、HTTP200 + SUCCESS 应答及主动查询兜底，再逐步开放实际业务。

1. 接入约定

专用网关：https://qiancipay.com/api/openapi/cpcn

全部接口使用 POST application/json; charset=utf-8。沿用千词支付已有 app_id 和平台签名密钥，不向商户下发中金私钥。此接口需由平台为各商户单独开放、配置独立机构与证书、明确固定技术费及通道成本并验证；完成后商户后台显示本页入口。文档可见不等于交易已开启，真实新交易还须全局及该商户对应能力开关均开启。

• 所有金额为整数“分”：59元传5900，59.9元传5990。不要传浮点元。
• 响应格式 {"code":0,"msg":"ok","data":{...}}。HTTP200只说明HTTP请求完成；先判断 code，再检查 data.status。中金已建单后的明确交易失败也可能返回 code=0、data.status=failed，不能把 code=0 或 msg=ok 当作扣款成功；非0业务码按错误含义处理。
• 中金与首信易、快钱的绑卡记录不可混用。中金业务统一使用本页专用接口，不能仅向旧接口增加 channel=cpcn。常规手工扣款/退款表单不受理中金交易；商户后台提供独立中金扣款、退款和解绑面板。
• 平台技术服务费、扣费模板、绑卡成功周期限制、月度限制、商户停用及扣款风控继续有效。失败不占成功额度，待确认订单保留额度，避免并发重复成功。
• 时间采用北京时间。结算安排以本商户与中金的约定为准；受理成功不等同于退款已到账。对接时使用平台字符串业务状态，不直接把中金底层数字状态码套用到各业务。
• 本页金额、单号均为报文示例，不是各商户默认价格；银行能力和费用以该商户当前配置及原单快照为准。

接口速查

以下全部为 POST，完整地址为“专用网关 + 路径”；每次调用均携带第2节公共签名参数。示例单号及金额仅用于说明，不是生产请求。

中金账户余额、提现、清算文件及电子回单不在本页开放范围。后台“中金对接文档”与本页使用同一份接口说明。

2. 签名与鉴权

除 sign 外的所有非空字段，按键名字典序排序，按 k=v&k=v 拼接，使用平台 App Secret 计算 HMAC。值不进行 URL 编码；不要额外发送嵌套对象或未定义字段。HTTP JSON编码的转义不属于签名原文。

可复制的 Node.js 18 客户端（仅自动执行只读银行查询）

保存为 cpcn-client.cjs，在服务器安全设置环境变量 QC_APP_ID、QC_APP_SECRET 后运行 node cpcn-client.cjs。不要把真实密钥写入代码、网页、URL或日志。例子默认读取贷记卡银行；尚未开通贷记卡时，把最后的 CREDIT_CARD 改为 DEBIT_CARD 验证借记卡能力。

'use strict';
const crypto = require('node:crypto');
const BASE = 'https://qiancipay.com/api/openapi/cpcn';
const APP_ID = process.env.QC_APP_ID;
const APP_SECRET = process.env.QC_APP_SECRET;

function sign(params) {
  const text = Object.keys(params)
    .filter(k => k !== 'sign' && params[k] != null && params[k] !== '')
    .sort().map(k => `${k}=${params[k]}`).join('&');
  return crypto.createHmac('sha256', APP_SECRET).update(text, 'utf8').digest('hex');
}

async function cpcnRequest(apiPath, fields = {}) {
  if (!APP_ID || !APP_SECRET) throw new Error('请先设置 QC_APP_ID / QC_APP_SECRET');
  const allowed = new Set(['/banks', '/bindcard', '/bindcard/confirm', '/bindcard/query',
    '/pay', '/pay/query', '/refund', '/refund/query', '/unbind', '/unbind/query']);
  if (!allowed.has(apiPath)) throw new Error('请使用本文列出的接口路径');
  const body = { ...fields, app_id: APP_ID,
    timestamp: String(Math.floor(Date.now() / 1000)),
    nonce: crypto.randomBytes(16).toString('hex') };
  body.sign = sign(body);
  let response, result;
  try {
    response = await fetch(BASE + apiPath, {
      method: 'POST', headers: { 'Content-Type': 'application/json; charset=utf-8' },
      body: JSON.stringify(body), signal: AbortSignal.timeout(15000)
    });
    result = await response.json();
  } catch (cause) {
    const error = new Error('请求或响应未确认：保留原业务单号，先查原单，不要自动换号重发', { cause });
    error.code = 'RESULT_UNKNOWN'; throw error;
  }
  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}：响应未确认，请查询原业务单号`);
    error.code = 'RESULT_UNKNOWN'; error.http_status = response.status; throw error;
  }
  if (!result || result.code !== 0) {
    const error = new Error(result?.msg || result?.message || '响应缺少有效平台业务码');
    error.code = result?.code ?? 'RESULT_UNKNOWN'; error.http_status = response.status;
    error.result = result; throw error; // 5030同样先查原单；这里绝不自动重试。
  }
  return result.data; // 仍需判断 data.status；code=0也可能是明确失败。
}

// 以下自动运行的唯一请求是银行列表，不绑卡、不扣款、不退款、不解绑。
if (require.main === module) {
  cpcnRequest('/banks', { card_type: 'CREDIT_CARD' })
    .then(data => console.log(JSON.stringify(data, null, 2)))
    .catch(error => { console.error(error.code || 'CLIENT_ERROR', error.message); process.exitCode = 1; });
}
module.exports = { cpcnRequest, sign };

签名使用最终上送的字段和值，不要先 URL 编码、不要签名后再改 amount/notify_url。中文按 UTF-8，金额单位为整数分；可选参数不传就不要自行加默认空对象。每次请求生成新的 timestamp/nonce，但原业务单号必须保持。

业务代码如何使用（以下仅展示，不自动执行）

// 在你的业务服务中按实际时机调用，先完成参数、持卡人授权和金额校验。
// const { cpcnRequest } = require('./cpcn-client.cjs');
// const card = await cpcnRequest('/bindcard', bindFields); // 参数见下一节
// const pay = await cpcnRequest('/pay', payFields);        // 会真实扣款
// if (pay.status === 'success') { /* 幂等确认成功 */ }
// else if (pay.status === 'failed') { /* 记录 pay.fail_reason，不重复发货 */ }
// else { /* 保存原 out_trade_no，用 /pay/query 查询，不生成新号 */ }
// const refund = await cpcnRequest('/refund', refundFields); // 会申请真实退款
// const unbind = await cpcnRequest('/unbind', { bind_id: existingBindId }); // 会撤销签约

后续各接口给出的“业务参数示例”不含公共字段，也不是完整可直接发送的签名请求；请交给上面的 cpcnRequest 合并公共参数并签名。代码中没有资金请求自动重试循环，请勿在外层套用通用 HTTP 自动重试器。

3. 绑卡与解绑

POST /banks

公共字段之外可选传入 card_type：DEBIT_CARD 为借记卡（默认），CREDIT_CARD 为贷记卡（信用卡）。返回所选 card_type、该卡型对应的 banks:[{code,name}] 和 binding_way（40一键/10短信）。银行编码必须来自所选卡型的清单，借贷记名单不能合并，也不能直接沿用首信易/快钱编码；不传 card_type 的旧商户仍使用借记卡。

贷记卡需由平台单独启用，仅支持银行一键绑卡（binding_way=40），当前不支持短信绑卡（10）或CVN方案。商户仅传上述 card_type 字符串，不要传中金内部 BankCardType 数字10/20，也不要自行传 binding_way 改变通道配置。

各商户独立银行能力

实际请求前须按 card_type 调用 /banks 获取本商户最新银行编码和名称，不应硬编码其他商户的银行矩阵。借记卡和贷记卡分别配置、分别判断停用状态；银行支持某项业务不代表本机构已获相应权限。未开通的卡型不能通过更换 bank_code 绕过。

POST /bindcard

以下为一键绑卡业务参数示例；尖括号内容须替换为经持卡人授权的真实资料，并合并公共参数后签名。不要把示例占位内容提交到生产环境。

{
  "out_bind_no":"YOUR_BIND_001","out_user_id":"YOUR_USER_001",
  "name":"<真实姓名>","id_card_num":"<18位身份证>",
  "phone":"<银行预留手机号>","bank_code":"<从banks取得的编码>",
  "card_type":"DEBIT_CARD",
  "notify_url":"https://merchant.example.com/notify/bind",
  "return_url":"https://merchant.example.com/bind/result"
}

返回 bind_id（平台绑卡编号）、status、channel:cpcn、card_type（DEBIT_CARD/CREDIT_CARD）、redirect_url、need_sms、card_mask。一键绑卡有 redirect_url 时引导用户打开；平台签约跳转会话有效期30分钟，银行页面有效期以银行实际提示为准。同步返回页不表示成功，商户应以通知/查询为准。

{"code":0,"msg":"ok","data":{
  "bind_id":12345,"out_user_id":"YOUR_USER_001","channel":"cpcn",
  "status":"submitting","bank_code":"104","card_type":"DEBIT_CARD",
  "card_mask":"","redirect_url":"https://qiancipay.com/bind/cpcn/redirect/EXAMPLE_TOKEN",
  "need_sms":false
}}

POST /bindcard/confirm

字段：bind_id、sms_code（6位）。仅借记卡短信快捷绑卡使用；借记卡或贷记卡一键绑卡均在银行页面完成，无需调用。验证码失败不直接等同于原签约最终失败，应查询确认；本版不提供短信重发接口。

POST /bindcard/query

字段：bind_id 或 out_bind_no（请求超时未取得bind_id时使用，二选一即可）。返回绑定记录的 card_type（DEBIT_CARD/CREDIT_CARD）及本地已确认状态：submitting待确认、bound成功、failed失败、unbound已解绑；失败时有 fail_reason。后台通过上游通知和定时查询收敛状态，查询不会重复绑卡。暂时没有 redirect_url 不代表签约成功或失败，仍应查询原 out_bind_no/bind_id，不要自动生成新的签约号。

POST /unbind

完整地址：https://qiancipay.com/api/openapi/cpcn/unbind。业务必填字段为本商户的中金 bind_id，同时携带原有公共字段 app_id、timestamp、nonce、sign；签名方式不变。无需上送姓名、身份证、卡号或中金证书，也不要自行生成新的解绑流水。平台使用该绑定的原中金流水和原证书版本发起解绑。

只接受已成功绑定的中金记录。code=0不等于已经解绑，必须同时检查 data.unbind_status 与原卡状态 data.status：只有确认成功后，卡状态才变为 unbound。处理中卡仍可能显示 bound，不得据此认定解绑成功；超时或结果未知时只查询原 bind_id，不要换号或重新绑定来重试。

{"code":0,"msg":"ok","data":{
  "bind_id":12345,"channel":"cpcn","status":"bound",
  "unbind_status":"processing","unbind_fail_reason":null,
  "last_checked_at":"2026-10-31 12:00:00"
}}

POST /unbind/query

完整地址：https://qiancipay.com/api/openapi/cpcn/unbind/query。公共签名参数与 /unbind 相同，业务字段仍为 bind_id。该接口只读取平台本地的已确认解绑状态，不重新发起解绑；平台通过中金通知和后台查询核验原解绑结果。

明确失败的提交可能返回业务码 4121，并携带可查询的解绑状态；查询失败或 5030 不代表原解绑失败。已经存在的处理中或失败记录不会因为再次调用而自动重发上游指令。关闭新绑卡、扣款或全局新交易能力，不妨碍已有有效授权的主动解绑；账户、合作签约及API权限仍按原有鉴权规则检查。

4. 扣款与查询

POST /pay

业务参数示例（需合并公共签名参数）：

{"out_trade_no":"YOUR_ORDER_001","bind_id":12345,"amount":5990,
 "goods_name":"商品服务","notify_url":"https://merchant.example.com/notify/pay"}

{"code":0,"msg":"ok","data":{
  "out_trade_no":"YOUR_ORDER_001","trade_no":"Q...",
  "pay_order_no":"20261027...","amount":5990,"fee":100,
  "status":"paying","channel":"cpcn"
}}

平台持久化订单后进入独立队列，在约5秒同步等待窗口内已确认的结果返回 success 或 failed；排队中、上游超时或结果未确认返回 paying。失败时附 fail_reason。fee 仅表示平台技术服务费，不包含中金通道费；以原支付的费用快照为准，不由当前配置追溯重算。

中金独立计费

每个商户分别约定中金固定技术服务费（元/笔）和通道成本；平台技术费从商户预付费余额扣收，与中金通道费分开。固定技术费必须明确设置，0表示明确不收取；未配置时不能开启新交易，不会默默沿用首信易、快钱的技术费率。通道成本按本商户费率及单笔最低费配置计算。订单创建时保留原配置及费用快照，后续换证或调价不改变原单计费；首信易、快钱既有计费不受影响。

POST /pay/query

字段：out_trade_no。返回同样的订单字段；全额退款后的支付单为 refunded，表示原支付成功且已退款。兼容历史数据时仍可能读到 part_refunded，但本版不接受新的部分退款。查询不重新扣款。失败订单如果确需重新支付，应核实失败后使用新的商户单号。

5. 全额退款与查询

POST /refund

必填 out_trade_no（原支付单）、out_refund_no（商户退款单号≤64字符）、amount（正整数分）；选填 reason（≤200字符）、notify_url。中金仅支持原支付全额退款，amount 必须等于原支付本金；不支持部分退款或把一笔原支付拆成多笔退款。部分退款返回 4306，平台在本地拒绝，不向中金发送退款请求。未完成退款会预占可退本金，防止并发重复退款。

业务参数示例（需合并公共签名参数，金额须等于该原支付本金）：

{"out_trade_no":"YOUR_ORDER_001","out_refund_no":"YOUR_REFUND_001",
 "amount":5990,"reason":"客户申请全额退款",
 "notify_url":"https://merchant.example.com/notify/refund"}

{"code":0,"msg":"ok","data":{
  "out_refund_no":"YOUR_REFUND_001","refund_no":"RF...",
  "pay_refund_no":"20261027...","amount":5990,
  "status":"processing","channel":"cpcn",
  "refund_fee_amount":0,"refund_fee_charged_amount":0,
  "refund_fee_status":"not_required","returned_channel_fee":null
}}

POST /refund/query

字段：out_refund_no。本金退款状态 status：processing待确认，success中金确认退款成功，failed明确失败（含fail_reason）。中金受理成功不等于退款成功；实际到账时间以银行为准。

查询读取平台本地已确认的订单状态，由中金异步通知及平台后台主动对账更新，并非每次商户查询都直连中金。查询不会重新发起退款；处理中请保留原退款单号，不要换号重复提交。

退款核验信息（兼容新增，可选）

退款响应、退款查询可能增加 refund_tracking 对象，不改变原有 status、单号或金额字段。历史记录或暂未取得追踪信息时字段可为 null/unknown；不要推定未记录就代表未收到通知或未进行查询。

退款手续费规则：原费用不退，不再补收

中金退款不退原通道手续费，平台原技术服务费也不退。平台只退原支付本金，不因退款从商户预付费余额额外扣费，也不从持卡人退款本金扣除费用。例如原通道手续费200分、技术服务费100分，则退款后仍保留原300分费用，不再追加200分。示例价格不适用于全部商户。

本规则统一用于中金退款，包括原支付费用快照曾启用补收的旧订单；旧补收开关、迟到通知、主动查询及充值均不会重新触发退款手续费补收。已实际发生的历史费用流水保留原记录，不自动冲正或再次收费。首信易、快钱计费与退款规则不变。

商户请求、签名、本金退款状态及异步通知流程保持不变。为兼容已有接入，下列可选费用字段继续保留，金额均为整数分；费用状态独立于本金 status，不能据“无需补收”认定退款已成功。费用信息变化不会另行触发本金终态通知，历史费用以查询和账单为准。

6. 异步通知

平台向该笔请求的 notify_url 发送 JSON，沿用相同 HMAC-SHA256 算法。通知包含公共签名字段及 event（bindcard/payment/refund）、channel:cpcn 和相应业务编号、金额、状态。绑卡通知（event=bindcard）还包含绑定记录的 card_type（DEBIT_CARD/CREDIT_CARD），该字段参与验签。不要把中金底层 XML 通知地址配置成商户地址。

{
  "app_id":"YOUR_APP_ID","timestamp":"...","nonce":"...","sign":"...",
  "event":"payment","channel":"cpcn","out_trade_no":"YOUR_ORDER_001",
  "trade_no":"Q...","pay_order_no":"20261026...",
  "amount":5990,"fee":100,"status":"success"
}

• 先验证签名、商户归属、业务单号及金额，再持久化处理。请兼容未知新增字段参与验签。
• 处理成功返回 HTTP200，正文纯文本 SUCCESS（大小写均兼容），不要返回JSON或HTML页面。
• 通知可能重复或早于接口响应；以业务单号+事件幂等处理，避免重复发货。同步已确认结果仍可能收到通知。
• 通知签名的 timestamp/nonce 可能在重试时保持原值，不能直接套用请求接口300秒去重规则；应按业务状态做幂等验签。
• 未确认通知按原平台规则退避重推，最多8次，失败可由管理端查看投递记录/重推；商户也应主动查询兜底。
• 未传 notify_url 不推送，必须通过查询取得结果。商户后台手动退款不填写商户通知地址，结果请在后台查询，不会自动继承原支付的通知地址。浏览器 return_url 不可作为付款/签约成功凭证。
• 本金退款与手续费处理独立，手续费后续状态变化以查询及账单为准，不新增本金终态回调事件；原有商户通知流程保持不变。

7. 错误与重试规则

业务状态速判：先区分是什么业务

幂等维度：绑卡 商户+out_bind_no，扣款 商户+out_trade_no，退款 商户+out_refund_no，解绑使用原 商户+bind_id。重试必须保持原业务参数，换新的 timestamp/nonce 并重新签名。同号变更金额或绑卡不会修改已受理订单，也不会再次发起资金交易；不要依赖响应存在 idempotent 标志判断幂等，始终核对返回的原单号、金额和业务状态。

超时、5030或查询暂未找到（如4210/4310）均不能单独证明原扣款/退款失败；保留原号，先查询和联系平台核实，不要自动换号重发资金请求。明确 failed 后确需再次扣款或申请退款，应先处理原失败原因，再按新业务申请发起；原成功退款不得再退，原明确失败解绑记录须联系平台核实而非自动清除重试。

本版提供绑卡、短信确认、解绑、扣款、退款、本地状态查询和上游异步/主动对账。中金账户余额、提现、清算对账文件及电子回单未在此文档开放，不能直接调用SDK中的其它交易码。

8. 常见问题：现象 → 排查 → 处理

先看返回的是接口业务码，还是 data.status=failed 内的上游失败原因。下面的“处理”不代表可以自动再扣一次；不确定原交易结果时，始终查原单。

9. 上线前自查与问题反馈

• 确认是本商户获批的生产配置、API及对应交易能力，不把文档可见/本地证书验证当作银行权限已验收。
• 借记与贷记分别用/banks取名单，按真实卡型绑卡；不硬编码所有商户共用的银行列表。
• 所有金额使用整数分；商户扣款金额满足当前模板，技术费预付余额与通道结算资金分开核对。
• 保存 out_bind_no/bind_id、out_trade_no/trade_no、out_refund_no/refund_no，接口超时不换号自动重发。
• 分别处理HTTP状态、平台code、各业务status及fail_reason；不能只看到code=0就认定付款成功。
• 回跳页只展示待核实并查询；回调验签、幂等持久化、提交后SUCCESS应答和主动查单兜底均经过验收。
• 退款测试只全额退本金，原通道费/技术费保留、不补收；解绑测试要经持卡人/商户确认，会真实撤销签约。
• 先少量真实授权业务验证本商户银行、卡型及通知接收链路，再逐步开放，不以其他商户的成功记录替代自身验收。

联系平台时一次提供这些信息

环境：生产 / 测试（由平台确认，不自行换证书或网关）
通道：中金；接口：例如 /api/openapi/cpcn/pay/query
发生时间：YYYY-MM-DD HH:mm:ss（北京时间）
业务单号：out_bind_no / bind_id，或 out_trade_no / trade_no，或 out_refund_no / refund_no
现象：预期结果、实际HTTP状态、平台code、data.status及fail_reason
请求/响应：已脱敏的业务字段；不要提供平台App Secret、证书密码、私钥或完整卡证资料
回调问题：实际notify_url、平台投递HTTP状态、商户响应正文及接收时间
商户侧处理：是否已查原单、是否已入账/发货，是否出现重复通知

不通过群聊发送完整姓名、身份证、手机号、银行卡号或签名密钥。需要原始敏感报文时，由平台约定安全方式单独核查。不要为定位问题自行重复扣款、退款或解绑。