一、接口地址#

用途	地址
代收提交	POST /api/payment/deposit
代收查询	POST /api/payment/info
代付提交	POST /api/charge/receive
代付查询	POST /api/charge/info
余额查询	POST /api/inquire/account/info

二、签名规则#

1. 取所有请求参数（排除 sign 与空值），按参数名 ASCII 升序排列。
2. 拼接 key1=value1&key2=value2&...，末尾追加 &key=<secret_key>。
3. 对整串做 MD5、转小写，得到 sign。

⚠️ 金额固定两位小数（如 100.00）；value 做 URL-encode，空格编码为 %20（非 +）。

示例

参数：cus_code=MCH001, cus_order_sn=T20260917001, payment_flag=alipay_cny, amount=100.00
待签字串（ASCII 升序）：
amount=100.00&cus_code=MCH001&cus_order_sn=T20260917001&payment_flag=alipay_cny&key=你的密钥
sign = md5(上面整串) 转小写

三、代收下单 /api/payment/deposit#

参数	必填	说明
cus_code	✓	商户号
cus_order_sn	✓	贵司订单号（唯一）
payment_flag	✓	alipay_cny（支付宝）
amount	✓	金额，两位小数字串（如 100.00）
notify_url	选	异步回调地址
redirect_url	选	付款完成跳转
payer_name	选	付款人姓名（alipay_cny 走实名比对，请必须带入；须与实际付款支付宝账户实名一致）
sign	✓	见第二节

响应

{
  "result": 1, "status": "200", "message": "Success",
  "order_info": {
    "order_sn": "KF...",           // 我方订单号
    "cus_order_sn": "T20260917001",
    "currency_type": "CNY",
    "order_amount": "100.00",
    "payment_uri": "https://cashier.kf888.cash/pay/xxxx",  // 收银台，交付款人
    "order_status": "pending",
    "expired_at": "...", "created_at": "..."
  }
}

四、代付下单 /api/charge/receive#

当前代付仅支持 支付宝（打款至指定支付宝账户）。

参数	必填	说明
cus_code / cus_order_sn / amount / sign	✓	同代收
payment_flag	✓	pay_alipay_cny
account_name	✓	收款人姓名（支付宝实名）
bank_account	✓	收款支付宝账号
notify_url / attach_data	选	回调地址 / 附加数据（原样回传）

五、查询接口#

代收查询 /api/payment/info、代付查询 /api/charge/info、余额查询 /api/inquire/account/info。

查询参数：cus_code + order_sn（我方订单号）+ sign。

代收查询响应（含收款信息）

{
  "result": 1, "status": "200",
  "order_info": {
    "order_sn": "KF...", "cus_order_sn": "T...",
    "order_amount": "100.00", "receive_amount": "100.00",
    "order_status": "pending",                 // pending 待付款 / success 成功 / cancel 取消
    "payment_uri": "https://cashier.kf888.cash/pay/xxxx",   // 收银台，可直接交付款人
    "payment_img": "https://.../qr.png",       // 收款二维码（有则显示）
    "payment_detail": {                          // 收款账户（配好后才有，见下）
      "account_name": "张三",                    // 收款人姓名
      "account_no": "13800000000",              // 收款账号
      "bank_name": "支付宝"                       // 开户行/渠道
    }
  }
}

⚠️ 人工转账收款（跑分）— 请轮询查询取收款账户

此类订单的收款账户是「配单完成后」才产生（下单当下尚在为您分配收款人）。因此：

1. 调用 /api/payment/deposit 下单，拿到 order_sn（此时 payment_detail 可能为空）。
2. 每 2~3 秒轮询一次 /api/payment/info，直到响应带出 payment_detail（或 payment_img）。
3. 拿到收款账户后展示给付款人；也可直接把付款人导到 payment_uri（我方收银台，配好会自动显示）。
4. 轮询到 order_status = success 即到账（以异步回调为准），停止轮询。

说明：第三方渠道订单下单响应即含收款信息，无需轮询；仅人工转账（跑分）收款需按上述轮询取账户。

六、异步回调（notify_url）#

我方以 POST 推送支付结果到贵司 notify_url（来源 IP 52.68.208.119）。验签方式与下单一致。贵司处理成功后须回传纯文本 success，否则我方会重试。

字段	说明
order_sn / cus_order_sn	我方 / 贵司订单号
currency_type	CNY
original_amount / order_amount	原始 / 订单金额（两位小数字串）
status	success / fail / 其他
message	结果说明
receive_amount / fee_amount	实际到账 / 手续费
account_name / bank_account	代付收款信息（代付回调）
attach_data	下单时的附加数据，原样回传
sign	验签用

七、订单状态#

状态	说明
pending	待付款 / 处理中
success	成功（入账）
fail	失败
cancel	取消
expired	逾时未付款

八、对接流程#

1. 贵司放行回调 IP 52.68.208.119、提供 notify_url。
2. 我方开通商户号，回传 cus_code + secret_key。
3. 先代收／代付各一笔小额测试单，确认回调与验签通过后上量。

九、错误码#

接口失败时返回统一错误结构（HTTP 200，以 result 判断）：

{
  "result": "error",           // 成功为 1；失败为 "error"
  "status": 416,               // 错误码（见下表）
  "message": "No runner matched, order failed",
  "request_data": null
}

status	说明
300	金额错误（金额 ≤ 0，或手续费大于订单金额）
400	缺少必填参数（如 bank_cny 需 payer_name）
401	验签失败 / 商户不存在 / 无权访问该订单
403	代理账号不可直接下单 / 商户未配置费率 / 该币种+支付方式无费率
404	订单不存在（查询接口）
406	订单号重复（cus_order_sn 已存在）
416	未匹配到收款渠道/收款员，订单失败。同步配单模式下未配到收款员即返回此码（未成功建单，请重试或改期）
500	系统内部错误，请稍后重试或联系我方