ai_sdk
/
hb-20260724155322
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
hb
10 Commits 1 Branch 0 Tags 64 KiB
Go 100%
Go to file
renzhiyuan bab0d82b57 添加 README 文档 2026-07-24 15:53:28 +08:00
hb 添加文件: hb/valid.md 2026-07-24 15:53:28 +08:00
README.md 添加 README 文档 2026-07-24 15:53:28 +08:00

README.md

文档概述1111111

  • 接口总数：1个
  • 文档版本：2.0.0

认证与安全

安全控制

接口采用 HTTPS + 数据签名 的方式来保证商户与手机支付平台间的身份验证、中间信息传递的完整性，实现交易身份辨识、不可抵赖、防止篡改。

签名机制

签名算法分为 MD5 和 RSA 两种。

  1. MD5签名：

    • 在待签名数据之后加上商户密钥（signKey，64位密码串），生成MD5摘要用于签名。
    • 商户密钥由手机支付平台提供给商户。

  2. RSA签名：

    • 配合SHA-1数字签名算法实现数字签名功能。
    • 商户系统发送请求时：使用商户的私钥对签名值进行RSA加密，手机支付系统使用商户的公钥进行校验。
    • 手机支付系统返回数据时：使用手机支付的私钥对签名值进行RSA加密，商户使用手机支付的公钥进行校验。
    • 无需使用双方约定的商户密钥，减少密钥泄漏风险。

签名方法

  1. 签名源：请求参数按文档顺序（表格中从上到下顺序）拼接，其中 hmac、merchantCert、serverCert 字段不参与签名。
  2. 手机支付平台返回的中文字段先进行签名，再做 UTF-8 转码。

密钥来源

  • 商户号（merchantId）：手机支付平台提供给商户的唯一标识ID号。
  • 商户密钥（signKey）：手机支付平台提供给商户，用于接口调用的MD5数字签名算法的64位密码串。
  • 获取方式：登录手机支付平台 https://cmpay.10086.cn/merchant/index.jsp → "安全中心" → "密钥管理中心"。

接口列表

接口 1：退款接口

  • 路径：/ips/cmpayService
  • 方法：POST（基于HTTPS）
  • 描述：通过中国移动手机支付渠道，商家可以将已成功交易的款项退还给用户。
  • 提交地址：
    • 生产环境：https://ipos.10086.cn/ips/cmpayService
    • 测试环境：https://uatipos.10086.cn/ips/cmpayService
    • 注：测试环境有网络限制，需提供服务器出访公网固定IP；生产环境无网络限制。

请求参数

参数名 参数命名 最大长度 类型 说明 可否为空
商户编号 merchantId Max(50) String 手机支付平台给商户分配的唯一标识 否
商户请求号 requestId Max(50) String 商户请求的交易流水号，需要唯一，只代表当次退款接口的请求流水号，与下单接口中商户请求号无关联 否
签名方式 signType Max(3) String 只能是 MD5 或 RSA 否
接口类型 type Max(20) String OrderRefund 否
版本号 version Max(10) String 2.0.0 否
商户订单号 orderId Max(50) String 需要退款的商户订单号 否
退款金额 amount Max(10) Number 退款金额，以分为单位 否
商户证书公钥 merchantCert - - 不参与签名；如果 signType=RSA，此项也不需要传值 是
签名数据 hmac - - 获得 hmac 的方法见签名算法，参数顺序按照表格中从上到下的顺序，但不包括本参数 否

签名参数顺序（用于生成hmac）：merchantId, requestId, signType, type, version, orderId, amount（按表格从上到下顺序，不包括merchantCert和hmac）

响应参数

参数名 参数命名 最大长度 类型 说明 可否为空
商户编号 merchantId Max(50) String 手机支付平台给商户分配的唯一标识 否
流水号 payNo Max(50) String 手机支付平台返回的退款交易流水号，退款接口请求参数中商户请求号requestId在和包侧对应的和包退款流水号 否
返回码 returnCode Max(10) String 提示各类相关信息，000000和MCG00000表示当次退款请求成功，其余判断为退款请求失败。该字段不代表退款最终结果，退款最终结果请以返回参数中status字段的值做判断 否
返回码描述信息 message Max(256) String 返回码信息提示 是
签名方式 signType Max(3) String 只能是 MD5 或者 RSA 否
接口类型 type Max(20) String OrderRefund 否
版本号 version Max(10) String 2.0.0 否
退款金额 amount Max(10) Number 退款的金额，单位为分 否
商户订单号 orderId Max(50) String 需要退款的商户订单号 否
退款结果 status Max(10) String 退款结果。成功：SUCCESS；失败：FAILED 否
服务器证书公钥 serverCert Max(3000) String 若signType=RSA，该字段值为返回报文的验签使用的密钥 是
签名数据 hmac - - 以上请求参数生成的签名串，获得hmac的方法见签名算法，参数顺序按照表格中从上到下的顺序，但不包括证书公钥和本参数 否

响应签名参数顺序（用于验证hmac）：merchantId, payNo, returnCode, message, signType, type, version, amount, orderId, status（按表格从上到下顺序，不包括serverCert和hmac）

请求示例

hmac=441C1E65A2254E167EBF39E86BC1F0B7A82400B365D21BB072C6F960F304061BEA3204A72F0B45700DF1DFFE55DD622B91B973C6E4EC6665777E16E3D63E2FB07F8D041EAB8B1ECDBC726BEC2F8DC8856D315FAFA27E89191133D304ED8E356B999F86669A784CB2458E425D54A64126FC198D82DEB6B338F1943CBD9344506E1B7283EFB013D18101FD63D8103F5D57A0729E150CCE8AA7E07DD6B641176A2210EAA36C38214273BB1B9F5096FBDD9A292D7A724F0BCA3FFD630DC419FB7C2093063EA144041E28CF2A294F3A708544418046E43DF93E53E6DD935FC2BA4105F29ACDD4D240B8A9E2C58496673C9DD6C1270EE72E0E6E2F73F475B67367CC9D&&merchantId=888009941110054&requestId=20211105053044&signType=RSA&type=OrderRefund&version=2.0.0&orderId=20211105045315&amount=1

响应示例

merchantId=888009941110054&payNo=205206151912517707&returnCode=000000&message=SUCCESS&signType=RSA&type=OrderRefund&version=2.0.0&amount=1&orderId=20211105045315&status=SUCCESS&serverCert=3082042030820308A003020102020420B82E72300D06092A864886F70D0101050500302F310B300906035504061302434E3120301E06035504030C17434D434120456E74657270726973652043415F32303438301E170D3230303830363031343834395A170D3232303830363031343834395A3076310B300906035504061302434E310F300D06035504080C06E6B996E58D97310F300D06035504070C06E995BFE6B2993145304306035504030C3CE4B8ADE59BBDE7A7BBE58AA8E9809AE4BFA1E99B86E59BA2E6B996E58D97E69C89E99990E585ACE58FB8E794B5E5AD90E59586E58AA1E4B8ADE5BF8330820122300D06092A864886F70D01010105000382010F003082010A028201010092FCBC26F1107D35B966C0C098B1F31F8313103A29DC5C78A8056D1AFAC1E5BAA89F5AEE6D3E737D3554AE815040AD5A5D9BAF5BB5B4B45AA5622335E3B9F48D9C05DF29248DF944544D414513F37DFE7F618D0C62B24E1E90CFD1790791861E20FDEFC4288EA4BF906EE1A6B576D9FDE6108CF5A1ED01D1931F2C72AED5393AE9CB668BBF629B25A239E09C54D45B565FBA040963B011C7B80F7C93D4695F4568F6358D591FBCB1073C2583630EC858B7C21F5B7CBB8CC05431D93F4AC358F78A06D6E40D1C033083F403697C12A0A99FF6363D792F624B66FCA655E7057686BA5093A8F68597DB8F40865081A3EB43C1C52E91D35F83F9FF3BF40C9901D08B0203010001A381FC3081F930370603551D250101FF042D302B06082B0601050507030206082B0601050507030106096086480186F8420401060A2B0601040182370A0303301F0603551D23041830168014972A89BEE6A2AA3FA666133AE36A3FBA5D86697130710603551D1F046A30683066A02FA02D862B687474703A2F2F7777772E636D63612E6E65742F646F776E6C6F61642F63726C2F43524C3134322E63726CA233A431302F3120301E06035504030C17434D434120456E74657270726973652043415F32303438310B300906035504061302434E300B0603551D0F0404030200B1301D0603551D0E04160414F713DA66CF8A1F30440D83455C2AFC6560B040B6300D06092A864886F70D010105050003820101002AD8B85ABEEAE53C6002381120F7D6B23620464197FBBDB093D4BB98AF256E335F55A67E32BFDF165BB1E2DDA997A0727086D26F8427FE6B77F6F00C6168CE715E8D298D5EB47B7227CDB8094CB1047CBDEA3D911903DCAA57131DEE1CD0069BBF8C7940A3E68438CCCA1949FF045F7349AA865F7FAC7170B7D7339DEBC46930FF9B241200440EAFD280F868C13364D13ECEB04EA702D0479862F9590813AB94BE38DC84E366B884174731464111A1AFEB199E1D7D518651BB5F430926286CA2B5619CD54689F5851A231C1605146D4ACD6CCC54DB79CC49F992083D5DEACAFDDC2B8777B13B7D63FF7E35D1098BEFD6B550EC3328ECE0224F5AAD6C2B83FB85&PUB_CERT=3082042030820308A003020102020420B82E72300D06092A864886F70D0101050500302F310B300906035504061302434E3120301E06035504030C17434D434120456E74657270726973652043415F32303438301E170D3230303830363031343834395A170D3232303830363031343834395A3076310B300906035504061302434E310F300D06035504080C06E6B996E58D97310F300D06035504070C06E995BFE6B2993145304306035504030C3CE4B8ADE59BBDE7A7BBE58AA8E9809AE4BFA1E99B86E59BA2E6B996E58D97E69C89E99990E585ACE58FB8E794B5E5AD90E59586E58AA1E4B8ADE5BF8330820122300D06092A864886F70D01010105000382010F003082010A028201010092FCBC26F1107D35B966C0C098B1F31F8313103A29DC5C78A8056D1AFAC1E5BAA89F5AEE6D3E737D3554AE815040AD5A5D9BAF5BB5B4B45AA5622335E3B9F48D9C05DF29248DF944544D414513F37DFE7F618D0C62B24E1E90CFD1790791861E20FDEFC4288EA4BF906EE1A6B576D9FDE6108CF5A1ED01D1931F2C72AED5393AE9CB668BBF629B25A239E09C54D45B565FBA040963B011C7B80F7C93D4695F4568F6358D591FBCB1073C2583630EC858B7C21F5B7CBB8CC05431D93F4AC358F78A06D6E40D1C033083F403697C12A0A99FF6363D792F624B66FCA655E7057686BA5093A8F68597DB8F40865081A3EB43C1C52E91D35F83F9FF3BF40C9901D08B0203010001A381FC3081F930370603551D250101FF042D302B06082B0601050507030206082B0601050507030106096086480186F8420401060A2B0601040182370A0303301F0603551D23041830168014972A89BEE6A2AA3FA666133AE36A3FBA5D86697130710603551D1F046A30683066A02FA02D862B687474703A2F2F7777772E636D63612E6E65742F646F776E6C6F61642F63726C2F43524C3134322E63726CA233A431302F3120301E06035504030C17434D434120456E74657270726973652043415F32303438310B300906035504061302434E300B0603551D0F0404030200B1301D0603551D0E04160414F713DA66CF8A1F30440D83455C2AFC6560B040B6300D06092A864886F70D010105050003820101002AD8B85ABEEAE53C6002381120F7D6B23620464197FBBDB093D4BB98AF256E335F55A67E32BFDF165BB1E2DDA997A0727086D26F8427FE6B77F6F00C6168CE715E8D298D5EB47B7227CDB8094CB1047CBDEA3D911903DCAA57131DEE1CD0069BBF8C7940A3E68438CCCA1949FF045F7349AA865F7FAC7170B7D7339DEBC46930FF9B241200440EAFD280F868C13364D13ECEB04EA702D0479862F9590813AB94BE38DC84E366B884174731464111A1AFEB199E1D7D518651BB5F430926286CA2B5619CD54689F5851A231C1605146D4ACD6CCC54DB79CC49F992083D5DEACAFDDC2B8777B13B7D63FF7E35D1098BEFD6B550EC3328ECE0224F5AAD6C2B83FB85&hmac=00AAA308D1AA66B2E534D9177B408B55A0CC14F8B27ACE59F08150E66E51858F18070A0DD629FCBD47BB1A98A632DB3F492213A92F14885043EC68BD8180E58ED742D748B708B281693226A7D3BF326B812BA45E7E7D13B4D52498B3C6C83380827CD741A9EF0D99B1C96588C2BE56C79BDFC3813CA4E627142BA7717FFFB43BE53F9B3F2A6D3112D83A90C3D3859A8456BC892E6E960FE56F36F829FAFA7CAEF19D01D10C0BD2F2538827CFF4C642BBAA6423AED0CB8E0D980D7D0BDEB4B1A04B9DAC8867B724527423038D953603A07018BEC1980AD31EDD3E88977F72795DCFB0B3B674FA91A6443F9F0DB67B485B3F3AD5E48AA26F3641E44B64FC7B0920

错误码

错误码 说明 处理建议
000000 退款请求成功（不代表退款最终结果，需以status字段为准） -
MCG00000 退款请求成功（不代表退款最终结果，需以status字段为准） -
C01088 退货金额域非法 检查退款金额参数
C01081 产品名称域越界 检查产品名称参数
C01033 产品名称域为空 检查产品名称参数
C01030 有效期单位域不合法 检查有效期单位参数
C01028 有效期数量域为0 检查有效期数量参数
C01027 有效期数量域为空 检查有效期数量参数
C01025 订单日期域不合法 检查订单日期参数
C01024 订单日期域为空 检查订单日期参数
C01019 币种域取值不合法 检查币种参数
C01018 币种域为空 检查币种参数
C01014 订单金额域为空 检查订单金额参数
D99981 订单已过期 确认订单是否在有效期内
D23190 退款日期超过最大有效期 确认退款日期是否超期
D22407 退款金额大于可退款金额 检查退款金额是否超过可退金额
D22401 退货金额大于可退货金额 检查退货金额
D22208 订单状态异常 详询cmpay网站；除了订单号重复外，requestID也不能重复
D22201 订单不存在 确认订单号是否正确
D22224 账户支付方式不正确 联系CMPAY网站，检查type值及bankAbbr
D77040 商户没有开通此类交易的权限 联系平台确认权限
IPS0008 签名不符，一般都是由于中文编码引起 检查签名算法和编码（UTF-8）
IPS0001 一般都是因为商户编号或者密钥不对引起 检查商户编号和密钥

回调通知

文档中提及了两种通知机制（在业务术语中定义），但退款接口本身未提供具体的回调通知参数和地址配置说明：

  • 页面通知：页面跳转同步通知，手机支付系统处理完后，当前页面自动跳转回商户网站，携带处理结果信息。
  • 后台通知：服务器异步通知，手机支付平台主动发起通知给商户网站，携带处理结果信息。

附录：银行代码对照表

（保留完整对照表供参考）

银行代码 银行名称 银行代码 银行名称
ICBC 工商银行 HSB 徽商银行
CMB 招商银行 HUNRCU 湖南农村信用社
CCB 建设银行 JJB 九江银行
ABC 农业银行 JSB 江苏银行
BOC 中国银行 NBB 宁波银行
SPDB 上海浦东发展银行 NXB 宁夏银行
BCOM 交通银行 QLB 齐鲁银行
CMBC 民生银行 QSB 齐商银行
CEBB 光大银行 RZB 日照银行
GDB 广东发展银行 SCB 渣打银行
ECITIC 中信银行 SDRCB 顺德农村商业银行
HXB 华夏银行 SHRCB 上海农村商业银行
CIB 兴业银行 SJB 盛京银行
PSBC 邮政储蓄银行 SPABANK 平安银行
SDB 深圳发展银行 SRB 上饶银行
BBGB 广西北部湾银行 SZB 苏州银行
BEA 东亚银行 SZRCB 深圳农村商业银行
CBHB 渤海银行 TACCB 泰安市商业银行
CDRCB 成都农村商业银行 WHCCB 威海市商业银行
CQRCB 重庆农村商业银行 WLMQCCB 乌鲁木齐市商业银行
DGB 东莞银行 WZB 温州银行
DLB 大连银行 XMB 厦门银行
DYCCB 东营市商业银行 YCCCB 宜昌市商业银行
FDB 富滇银行 ZHRCU 珠海市农村信用合作社
GZB 广州银行 ZJCCB 浙商银行
HBB 河北银行 ZJGRCB 张家港农商银行
HKB 汉口银行 NCB 南洋商业银行
HZB 杭州银行 SHRCB 上海农村商业银行
LTCCB 浙江泰隆商业银行 CBHB 渤海银行
HSB 徽商银行 NJCB 南京银行
BJRCB 北京农商银行 BOB 北京银行