iOS开发之网银在线支付快捷支付商户接口规范
|
|||
|
|||
如果您在开发过程中遇到任何技术问题，可以咨询我们的技术支持人员：
联系邮箱：010-62428538、62428630
(1)商户根据网银在线支付平台提供的接口规则，生成加密报文信息，将请求发送至网银在线快捷支付地址
(2)网银在线支付系统对请求数据进行处理，进行安全校验等验证，一系列验证通过后便会解密报文中的加密信息，处理这次发送过来的数据请求。
(4)返回处理的结果数据
对于处理完成的交易会以两种方式把数据反馈给商户：
1)：前台通知： 交易结束后，网银在线实时发送给商户
2)：后台通知： 如果商户请求的数据中通知地址不为空，则服务器异步发起通知，按照商户在请求时上送的通知地址发送通知
(5)商户对获取的返回结果数据进行处理。
3 报文格式 ·
在网银在线快捷支付的所有交易中，请求和响应报文格式均为XML格式。
| 名词 |
描述 |
| 签约 |
使用快捷支付进行付款前，用户及银行卡信息须提交给银行进行验证，以保证信息的准确性。 |
| 支付 |
签约完成后，即可进行快捷支付；每次支付前都必须进行签约。 |
| Api访问地址 |
https://quick.chinabank.com.cn/express.htm |
3.3 响应机制
商户向API地址发送post请求，请求参数名称charset和req，charset是告诉快捷业务使用那种编码解码数据（具体查看字符编码表7.1），req是交易数据（具体数据格式看下文）。
商户发送交易数据至快捷业务，快捷业务处理请求，返回响应数据，resp=响应数据
有时可能由于商户网络原因没有接到同步响应结果，网银快捷支付、退款接口支持异步通知机制，异步通知机制推送3次响应数据，每次间隔为1分钟。
下文讲解如何发送和解析网银在线快捷支付数据。明文数据格式如：3.4请求/响应公共参数列表。注：各支付接口只有data不同；数据格式为XML形式。
3.4 请求/响应公共参数列表
| 字段名 |
变量名 |
类型 |
说明 |
可空 |
| VERSION |
版本号 |
String/10 |
1.1.0 |
N |
| MERCHANT |
商户号 |
String/10 |
由网银在线提供 |
N |
| TERMINAL |
终端号 |
String/10 |
由网银在线提供 |
N |
| DATA |
持卡人数据和交易数据 |
String |
按二级参数和三级参数组成XML格式数据，然后使用3DES加密。 |
N |
| SIGN |
数据签名 |
String/32 |
MD5签名，签名数据为所有参数加签名密钥 |
N |
3.5 请求相应XML样例
格式如下：
| 请求/响应公共报文：
元素是交易过程中的主要数据需要用3DES加密，加密密钥需要在网银在线后台设置； 元素一起用MD5加密之后的值，MD5加密密钥需要在网银在线后台设置； 发送请求时整个XML需要用BASE64编码之后发送 |
| 其中请求DATA元素格式如下
响应DATA元素格式如下：
|
4 接入范例
4.1 概述
网银在线提供快捷支付：快捷支付每次交易都要进行签约，每次签约时都需要输入验证码验证；
4.2 接入代码示例
1.XML中的元素用3DES加密.
2.
3.整个XML最后用BASE64编码.
4.发送POST请求到网线在线快捷支付地址，参数为req（加密之后的XML）、charset为xml字符编码方式.
5.得到网银在线返回信息后，用同样的方法解析.
注：元素中的具体内容，需要根据具体的业务逻辑决定。
5 签约确认快捷支付
5.1 含义
在进行支付前，收集持卡人的签约信息，提交至网银在线快捷支付地址，网银在线根据商户提供的持卡人的签约信息，完成签约的过程，每次交易之前都要进行签约。
5.2 签约请求DATA元素内容
交易请求接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
可空 |
| CARD |
BANK |
持卡人支付卡号发卡行 |
String/5 |
|
N |
| TYPE |
持卡人支付卡号卡类型 |
String/1 |
信用卡：C / 借记卡：D |
N |
|
| NO |
持卡人支付卡号 |
String/19 |
|
N |
|
| EXP |
持卡人信用卡有效期 |
String/4 |
年年月月 |
Y |
|
| CVV2 |
持卡人信用卡校验码 |
String/4 |
|
Y |
|
| NAME |
持卡人姓名 |
String/100 |
|
N |
|
| IDTYPE |
持卡人证件类型 |
String/1 |
身份证：I |
N |
|
| IDNO |
持卡人证件号 |
String/20 |
|
N |
|
| PHONE |
持卡人手机号 |
String/20 |
|
N |
|
| TRADE |
TYPE |
交易类型 |
String/1 |
V |
N |
| ID |
交易号 |
String/30 |
数字或字母 |
N |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
N |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
N |
5.3 签约响应DATA元素内容
交易回复接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
| TRADE |
TYPE |
交易类型 |
String/1 |
V |
| ID |
交易号 |
String/30 |
数字或字母 |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
|
| RETURN |
CODE |
交易返回码 |
String/10 |
|
| DESC |
交易返回码信息 |
String/100 |
|
5.4 消费请求DATA元素内容
交易请求接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
可空 |
| CARD |
BANK |
持卡人支付卡号发卡行 |
String/5 |
|
N |
| TYPE |
持卡人支付卡号卡类型 |
String/1 |
信用卡：C / 借记卡：D |
N |
|
| NO |
持卡人支付卡号 |
String/19 |
|
N |
|
| EXP |
持卡人信用卡有效期 |
String/4 |
|
Y |
|
| CVV2 |
持卡人信用卡校验码 |
String/4 |
|
Y |
|
| NAME |
持卡人姓名 |
String/100 |
|
N |
|
| IDTYPE |
持卡人证件类型 |
String/1 |
身份证：I |
N |
|
| IDNO |
持卡人证件号 |
String/20 |
|
N |
|
| PHONE |
持卡人手机号 |
String/20 |
|
N |
|
| TRADE |
TYPE |
交易类型 |
String/1 |
S |
N |
| ID |
交易号 |
String/30 |
数字或字母 |
N |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
N |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
N |
|
| DATE |
交易日期 |
String/8 |
yyyyMMdd |
Y |
|
| TIME |
交易时间 |
String/6 |
HHmmss |
Y |
|
| NOTICE |
通知地址 |
String/100 |
如果为空，交易结束后不主动向商户发送结果通知 |
Y |
|
| NOTE |
交易备注 |
String/100 |
原文返回 |
Y |
|
| CODE |
交易验证码 |
String/10 |
由网银校验验证码时必填 |
Y |
5.5 消费响应DATA元素内容
交易回复接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
| TRADE |
TYPE |
交易类型 |
String/1 |
S |
| ID |
交易号 |
String/30 |
数字或字母 |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
|
| DATE |
交易日期 |
String/8 |
yyyyMMdd（订单支付完成日期） |
|
| TIME |
交易时间 |
String/6 |
HHmmss（订单支付完成时间） |
|
| NOTE |
交易备注 |
String/100 |
原文返回 |
|
| STATUS |
交易返回状态 |
String/1 |
成功：0 / 处理中：6 / 失败：7 |
|
| RETURN |
CODE |
交易返回码 |
String/10 |
|
| DESC |
交易返回码信息 |
String/100 |
|
6 其他公共接口DATA元素内容
6.1 查询交易请求DATA元素内容
交易请求接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
可空 |
| TRADE |
TYPE |
交易类型 |
String/1 |
Q |
N |
| ID |
交易号 |
String/30 |
数字或字母 |
N |
6.2 查询交易响应DATA元素内容
交易回复接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
| TRADE |
TYPE |
交易类型 |
String/1 |
S |
| ID |
交易号 |
String/30 |
数字或字母 |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
|
| DATE |
交易日期 |
String/8 |
yyyyMMdd（订单支付完成日期） |
|
| TIME |
交易时间 |
String/6 |
HHmmss（订单支付完成时间） |
|
| NOTE |
交易备注 |
String/100 |
原文返回 |
|
| STATUS |
交易返回状态 |
String/1 |
成功：0 退款：3 失败：7 |
|
| RETURN |
CODE |
交易返回码 |
String/10 |
|
| DESC |
交易返回码信息 |
String/100 |
|
6.3 退款请求DATA元素内容
交易请求接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
可空 |
| TRADE |
TYPE |
交易类型 |
String/1 |
R |
N |
| ID |
交易号 |
String/30 |
数字或字母 |
N |
|
| OID |
原交易号 |
String/30 |
数字或字母 |
N |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
N |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
N |
|
| DATE |
交易日期 |
String/8 |
yyyyMMdd |
Y |
|
| TIME |
交易时间 |
String/6 |
HHmmss |
Y |
|
| NOTICE |
通知地址 |
String/100 |
如果为空，交易结束后不主动向商户发送结果通知 |
Y |
|
| NOTE |
交易备注 |
String/100 |
原文返回 |
Y |
6.4 退款响应DATA元素内容
交易回复接口DATA参数说明
|
|
字段名 |
变量名 |
类型 |
说明 |
| TRADE |
TYPE |
交易类型 |
String/1 |
R |
| ID |
交易号 |
String/30 |
数字或字母 |
|
| OID |
原交易号 |
String/30 |
数字或字母 |
|
| AMOUNT |
交易金额 |
String/12 |
单位：分 |
|
| CURRENCY |
交易币种 |
String/3 |
人民币：CNY |
|
| DATE |
交易日期 |
String/8 |
yyyyMMdd（退款请求发送日期） |
|
| TIME |
交易时间 |
String/6 |
HHmmss（退款请求发送时间） |
|
| NOTE |
交易备注 |
String/100 |
原文返回 |
|
| STATUS |
交易返回状态 |
String/1 |
成功：0 / 退款：3 / 部分退款：4 / 处理中：6 / 失败：7 |
|
| RETURN |
CODE |
交易返回码 |
String/10 |
|
| DESC |
交易返回码信息 |
String/100 |
|
7 附录
7.1 字符集编码表
| 编码 |
含义 |
| GBK |
GBK编码 |
| UTF-8 |
UTF-8编码 |
7.2 卡类型编码表
| 编码 |
含义 |
| C |
信用卡 |
| D |
借记卡 |
7.3 交易类型编码表
| 编码 |
含义 |
| V |
签约 |
| S |
消费 |
| Q |
查询 |
| R |
退款 |
7.4 币种编码表
| 编码 |
含义 |
| CNY |
人民币 |
7.5 交易返回状态编码表
| 编码 |
含义 |
| 0 |
成功 |
| 3 |
退款 |
| 4 |
部分退款 |
| 6 |
处理中 |
| 7 |
失败 |
7.6 交易返回信息编码表
| 返回码 |
返回信息 |
| 0000 |
成功 |
| 0001 |
处理中 |
| EEE0001 |
系统异常 |
| EEE0002 |
网络异常 |
| EEE0003 |
银行异常 |
| EEE0004 |
数据库异常 |
| EES0001 |
报文解析异常 |
| EES0002 |
字符集不正确 |
| EES0003 |
版本号不正确 |
| EES0004 |
商户号不正确 |
| EES0005 |
终端号不正确 |
| EES0006 |
交易数据不正确 |
| EES0007 |
数据签名不正确 |
| EES0008 |
权限不正确 |
| EES0009 |
密钥不正确 |
| EES0010 |
发卡行不正确 |
| EES0011 |
卡类型不正确 |
| EES0012 |
交易卡号不正确 |
| EES0013 |
卡有效期不正确 |
| EES0014 |
卡安全码不正确 |
| EES0015 |
持卡人姓名不正确 |
| EES0016 |
持卡人证件类型不正确 |
| EES0017 |
持卡人证件号不正确 |
| EES0018 |
持卡人手机号不正确 |
| EES0019 |
交易类型不正确 |
| EES0020 |
交易号不正确 |
| EES0021 |
交易金额不正确 |
| EES0022 |
交易币种不正确 |
| EES0023 |
交易日期不正确 |
| EES0024 |
交易时间不正确 |
| EES0025 |
交易通知地址不正确 |
| EES0026 |
交易备注不正确 |
| EES0027 |
交易验证码不正确 |
| EES0028 |
交易卡号网银不受理 |
| EES0029 |
交易卡号商户不受理 |
| EES0030 |
交易受理银行繁忙 |
| EES0031 |
交易受理渠道繁忙 |
| EES0032 |
交易重复 |
| EES0033 |
交易号重复 |
| EES0034 |
交易验证码申请不受理 |
| EES0035 |
交易验证码过期 |
| EES0036 |
交易不存在 |
| EES0037 |
原交易号不正确 |
| EES0038 |
原交易不允许此操作 |
| EES0039 |
原交易处理中 |
| EES0040 |
退款余额不足 |
| EES0041 |
查询银行列表错误 |
| EES0042 |
找不到相应的银行列表信息 |
| EES0043 |
卡号未签约 |
| EES0044 |
卡号未做签约申请 |
| EEB0001 |
银行交易不支持 |
| EEB0002 |
银行签约失败 |
| EEB0003 |
银行解约失败 |
| EEB0004 |
银行交易失败 |
| EEB0005 |
银行签约姓名校验失败 |
| EEB0006 |
银行签约手机号校验失败 |
| EEB0007 |
银行签约证件号校验失败 |
| EEB0008 |
银行签约卡有效期校验失败 |
| EEB0009 |
银行签约卡安全码校验失败 |
| EEB0010 |
银行不支持的卡类型 |
| EEB0011 |
银行不支持的卡号 |
| EEB0012 |
银行卡号状态异常 |
| EEB0013 |
银行卡号未开通快捷业务 |
| EEB0014 |
银行卡号余额不足 |
| EEB0015 |
银行单笔金额超限 |
| EEB0016 |
银行日交易金额超限 |
| EEB0017 |
银行日交易次数超限 |
| EER0001 |
风险校验失败 |