152 lines
15 KiB
Markdown
152 lines
15 KiB
Markdown
## 文档概述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 | 北京银行 | |