#iOS端控件支付产品接口规范文档4.0.0 [上海偶可贝网络科技有限公司](https://www.allpayx.com) * 版本信息：中文 V4.0.0 * 更新时间：2018 年4 月 #### 1.概述 AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实 现快速、安全、集中式的接入支付渠道。 #### 2.交易流程 ![image](https://git.allpayx.com/OpenAPI/b2c/raw/master/images/moble_sdk_flowsheet.png) #### 3.通用API说明 商户服务器和 AllPay 网关对接的通用接口,每个渠道都具有的功能,包括:消费,退款,查询接口。 ##### 3.1. 验签说明 ``` 1.对于发送到 ALLPAY 系统的 POST 请求报文，其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。 2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 K1(接入时 ALLPAY 时分配)，得到 stringSignTemp 字符串,并对 stringSignTemp 进行 md5 运算，得到 signature 的值。 3.示例签名串 acqID=99020344&backURL=https://www.baidu.com&charSet=UTF-8&frontURL=nil&goodsInfo=iPhone x&merID=800039253992510&merReserve=&orderAmount=1.00&orderCurrency=INR&orderNum=ap0180417163142&paymentSchema=EB&signType=MD5&transTime=20180417163142&transType=PURC&trxn_email_id=benson.zhang@allpayx.com&trxn_firstname=benson zhang&trxn_is_coupon_enabled=1&trxn_phone=15026528888&unique_id=abcde12345&version=VER000000002f3e0e436cd24430aa4aaaed597450f26 ``` ##### 3.2. 通用API 接入地址 交易名称 |开发调试地址|生产交易地址 ------- |-----------|------- 消费接口 |https://testapi.allpayx.com/app/pay |https://api.allpayx.com/app/pay 查询接口 |https://testapi.allpayx.com/pay |https://api.allpayx.com/pay 退款接口 |https://testapi.allpayx.com/pay |https://api.allpayx.com/pay ##### 3.3. 消费交易接口 1. 接口说明 商户网关将订单信息发送给 ALLPAY 网关，由 ALLPAY 网关进行处理后将交易流水 号，即 tn，返回给商户网关,tn 作为调起手机 app 支付控件的参数。 2. 请求报文格式 下面列举的字段为通用字段，每个渠道都需要上送，部分渠道有渠道专属字段，具体字段请到该渠道的专属渠到字段说明处查看 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |消费交易填写“PURC” 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|订单金额 |12|文本|orderAmount |如 100 元，表示为 100 或 100.00 6|订单币种 |3|文本|orderCurrency |人民币填写“CNY”,美元填写"USD" 7|前端 URL 地址 |400|文本|frontURL |app 模式默认填"nil" 8|后端 URL 地址 |400|文本|backURL |支付结果异步通知到该地址 9|商户预留字段 |1024 |文本|merReserve |商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 10|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 11|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 12|支付渠道代码 |10 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;印度本地支付:"EB" 13|商品信息 |60 |文本|goodsInfo | 商品信息 14|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 15|签名类型 |3 |文本|signType |MD5 16|签名 |32 |文本|signature |采用 MD5 签名 3. 响应报文格式 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|应答码 |2|文本|code |应答码，00成功 2|错误信息 |32|文本|msg |错误信息 3|交易流水号 |32|文本|tn |tn 作为调起 sdk 支付的参数,code等于"00"时返回该字段 ##### 3.4. 查询交易接口 1. 接口说明 该接口为接入商家提供交易查询的功能。 2. 请求报文格式 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |查询填写“INQY” 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|商户预留字段 |1024 |文本|merReserve |商户保留 6|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 7|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 8|支付渠道代码 |10 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;印度本地支付:"EB" 9|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 10|签名类型 |3 |文本|signType |MD5 11|签名 |32 |文本|signature |采用 MD5 签名 3. 响应报文格式 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |查询交易填写为“INQY 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|GW 交易 ID |32|文本|transID |GW 系统生成的交易 ID，每笔交易保持唯一 6|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 7|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 8|交易应答码 |2 |文本|RespCode |应答码 00-成功 9|应答文字信息 |20 |文本|RespMsg |应答消息，全部为英文字符 10|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 11|GW 处理时间 |14 |文本|GWTime |YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 12|签名类型 |3 |文本|signType |MD5 13|签名 |32 |文本|signature |采用 MD5 签名 ##### 3.5. 退款交易接口 1.接口功能说明 该接口为接入商家提供交易退款的功能。 2.请求报文格式 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |退款填写“REFD” 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|退款金额 |12|文本|returnAmount |如 100 元，表示为 100 或 100.00 6|订单币种 |3|文本|orderCurrency |人民币填写“CNY”,美元填写"USD" 7|商户预留字段 |1024 |文本|merReserve |商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 8|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 9|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 10|支付渠道代码 |10 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;印度本地支付:"EB" 11|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 12|签名类型 |3 |文本|signType |MD5 13|签名 |32 |文本|signature |采用 MD5 签名 3.响应报文格式 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |退款填写“REFD” 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|GW 交易 ID |32|文本|transID |GW 系统生成的交易 ID，每笔交易保持唯一 6|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 7|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 8|交易应答码 |2 |文本|RespCode |应答码 00-成功 9|应答文字信息 |20 |文本|RespMsg |应答消息，全部为英文字符 10|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 11|GW 处理时间 |14 |文本|GWTime |YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 12|签名类型 |3 |文本|signType |MD5 13|签名 |32 |文本|signature |采用 MD5 签名 #### 4.iOS 客户端接入步骤 ##### 4.1. 接入说明 ``` 启动支付控件的接口，接口定义如下: [AllPaySDK pay:[diction objectForKey:@"tn"] mode:NO scheme:@"com.xxx.xxx" ViewController:self onResult: ^(NSDictionary *resultDic) { //此处处理同步支付结果 }]; tn:是从服务器端获取的流水号; mode:测试环境:NO; 生产环境:YES。 Scheme: 可以为任意值推荐填写成"com.xxx.xxx" 等形式, 有特殊配置的渠道会在渠道专属配置里面说明 ViewController:调用 SDK 时的 ViewController; onResult:接收同步结果通知 ``` ##### 4.2. 添加 SDK 包 ``` 1. 将 allpaysdk 下的 AllPaySDK.h,libAllPaySDK.a文件add到项目中 2. 在 APPDelegate.m 类中导入头文件: #import "allpaysdk/AllPaySDK.h" 并添加如下方法 -(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{ [AllPaySDK openURL:url]; return YES; } -(BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{ [AllPaySDK openURL:url]; return YES; } -(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options{ [AllPaySDK openURL:url]; return YES; } 3. 根据要使用的渠道的专属配置，对项目进行配置 ``` #####4.3 同步结果通知 ``` [AllPaySDK pay:[diction objectForKey:@"tn"] mode:NO scheme:@"com.xxx.xxx" ViewController:self onResult: ^(NSDictionary *resultDic) { //此处处理同步支付结果 }]; resultDic,转为 json 字符串,格式如下: {"state": "cancel", "paymentSchema": "YL", "orderNum": "604337497032", "errorDetail": "user cancel operation " } - state: "success"代表成功, "cancel"代表用户取消操作, "fail"代表失败 - paymentSchema:支付渠道, 印度本地支付:"EB", "APMP"代表支付宝, "WX"代表微信,"APP"代表ApplePay - orderNum:订单号 - errorDetail:错误详情 ``` ##### 4.5. 异步结果通知 商户需要提供一个 http 协议的接口，包含在参数里传递给 SDK，即 backURL。AllPay 服务器在支付完成后，会以 Get 方式调用 backURL，通知支付结果。 参数如下表: 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1|版本号|12|文本|version |统一填写为“VER000000002” 2|字符集编码 |6|文本|charSet |统一填写为“UTF-8” 3|交易类型 |4|文本|transType |消费交易填写“PURC” 4|订单号 |60|文本|orderNum |商户自行定义，需保证同一商户号下订单号不能重复 5|订单金额 |12|文本|orderAmount |如 100 元，表示为 100 或 100.00 6|订单币种 |3|文本|orderCurrency |人民币填写“CNY”,美元填写"USD" 7|清算金额 |12 |文本|settAmount |如 100 元，表示为 100 或 100.00 8|清算币种 |3|文本|settCurrency |符合 ISO 标准，填写数字类型 9|清算汇率 |7|文本|rate |实际汇率，7 位有效数字 10|商户预留字段 |1024 |文本|merReserve |商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 11|GW 交易 ID |32|文本|transID |GW 系统生成的交易 ID，每笔交易保持唯一 12|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配 13|收单行 ID |11 |文本|acqID |收单行 ID "99020344" 14|支付渠道代码 |10 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;印度本地支付:"EB" 15|交易应答码 |2 |文本|RespCode |应答码 00-成功 16|应答文字信息 |20 |文本|RespMsg |应答消息，全部为英文字符 17|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss" 18|GW 处理时间 |14 |文本|GWTime |YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 19|签名类型 |3 |文本|signType |MD5 20|签名 |32 |文本|signature |采用 MD5 签名 #### 5.渠道专属配置 ##### 5.1 EB渠道 * 渠道专属配置: 1.将allpaysdk/EBModule文件夹下的文件add到项目中 2.Set Always embed swift standard libraries to YES from project build settings  ``` ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES ``` 3.To simply disable ATS, you can follow this steps by open Info.plist, and add the following lines: ``` NSAppTransportSecurity NSAllowsArbitraryLoads ``` * 消费接口专属字段 * 请求报文 序号 |名称 |长度|类型|参数名称|备注 -----|-----|----|----|------|------ 1| 姓名 |32 |文本|trxn_firstname |This is name of the customer who is doing the transaction. 2| 邮箱 |40 |文本|trxn_email_id |this is email id of the customer who is doing transaction. 3|电话 |20 |文本|trxn_phone|Phone number of the customer. 4|优惠券选项 |1 |文本|trxn_is_coupon_enabled| If the value is 0 then customer will not be able to see the coupons. If the value is 1 then customer will be able see the coupons and able to select the coupons 5|客户id |10 |文本|unique_id|This is customer’s unique id.不能超过10位