#iOS端控件支付产品接口规范文档4.3.1
[上海偶可贝网络科技有限公司](https://www.allpayx.com)
* 版本信息：中文 V4.3.1
* 更新时间：2018 年12 月
#### 1.概述
AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实 现快速、安全、集中式的接入支付渠道。
#### 2.交易流程
#### 3. 验签说明
```
1.对于发送到 ALLPAY 系统的 POST 请求报文，其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。
2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 K1(接入时 ALLPAY 时分配)，得到 stringSignTemp 字符串,并对 stringSignTemp 进行 md5 运算，得到 signature 的值。
3.示例签名串 acqID=99020344&backURL=https://baidu.com&charSet=UTF-8&detailInfo=W3siZ29vZHNfbmFtZSI6IuWNjuS4ulAyMCIsInF1YW50aXR5IjoiMiJ9LHsiZ29vZHNfbmFtZSI6IuWNjuS4ulAyMCBwbHVzIiwicXVhbnRpdHkiOiI0In1d&frontURL=https://mchapi.allpayx.com/demo&goodsInfo=华为P20&merID=000000000000015&merReserve=你好&orderAmount=1&orderCurrency=HKD&orderNum=dKmdb4S9Tv1a9ZpkMjeDawV82MCJ&paymentSchema=AP&signType=MD5&transTime=20181206134515&transType=PURC&version=VER0000000022f2c77e3718c47cfb47a89a6fbc9d361
```
#### 4.通用API说明
商户服务器和 AllPay 网关对接的通用接口,每个渠道都具有的功能,包括:消费,查询，退款,退款查询接口。
##### 4.1. 通用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/refund> | <https://api.allpayx.com/refund> |
| 退款查询接口 | <https://testapi.allpayx.com/refundquery> | <https://api.allpayx.com/refundquery> |
##### 4.2. 消费交易接口
1.接口说明
商户网关将订单信息发送给 ALLPAY 网关，由 ALLPAY 网关进行处理后将交易流水 号，即 tn，返回给商户网关,tn 作为调起手机 app 支付控件的参数。
2.请求报文格式
下面列举的字段为通用字段，每个渠道都需要上送，部分渠道有渠道专属字段，具体字段请到该渠道的专属渠到字段说明处查看
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 消费交易填写“PURC” |
| orderNum | String(60) | M | 订单号：商户自行定义，需保证同一商户号下订单号不能重复 |
| orderAmount | String(12) | M | 订单金额：如 100 元，表示为 100 或 100.00 |
| orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" |
| frontURL | String(400) | M | app 模式默认填"nil" |
| backURL | String(400) | M | 支付结果异步通知到该地址 |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击查看详情](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| goodsInfo | String(60) | M | 商品信息 |
| detailInfo | String(400) | M | 商品明细格式：[{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}]，需对该字段进行base-64编码后签名上送。 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | 采用 MD5 签名 |
3.响应报文格式
| 参数 | 类型 | 属性 | 描述 |
| ---- | ---------- | ---- | ---------------------------------- |
| tn | String(32) | M | 交易流水号,作为调起 sdk 支付的参数 |
4.商户需要提供一个 http/https 协议的接口，包含在参数里传递给 SDK，即 backURL。AllPay
服务器在支付完成后，会以 Get 方式调用 backURL，通知支付结果。
参数如下表:
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 消费交易填写“PURC” |
| orderNum | String(60) | M | 订单号 |
| orderAmount | String(12) | M | 订单金额：如 100 元，表示为 100 或 100.00 |
| orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" |
| settAmount | String(12) | M | 清算金额：如 100 元，表示为 100 或 100.00 |
| settCurrency | String(3) | M | 清算币种：符合 ISO 标准 |
| rate | String(7) | M | 实际汇率，7 位有效数字 |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode | String(2) | M | 应答码 00-成功 |
| RespMsg | String(20) | M | 应答消息，全部为英文字符 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | signature |
##### 4.3. iOS 客户端接入步骤
##### 4.4.1. 接入说明
启动支付控件的接口，接口定义如下:
```c
[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.4.2. 添加 SDK 包
1. 将 allpaysdk 下的 AllPaySDK.h,libAllPaySDK.a文件add到项目中
2. 在 APPDelegate.m 类中导入头文件: #import "allpaysdk/AllPaySDK.h" 并添加如下方法
```c
-(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<NSString *,id> *)options{
[AllPaySDK openURL:url]; return YES;
}
```
3. 根据要使用的渠道的专属配置(见第5节），对项目进行配置
##### 4.4.3 同步结果通知
```c
[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.4. 查询交易接口
1. 接口说明
该接口为接入商家提供交易查询的功能。
2 .请求报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 查询填写“INQY” |
| orderNum | String(60) | M | 订单号 |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | 采用 MD5 签名 |
1. 响应报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 查询填写“INQY” |
| orderNum | String(60) | M | 订单号 |
| transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode | String(2) | M | 应答码 00-成功 |
| RespMsg | String(20) | M | 应答消息，全部为英文字符 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | signature |
##### 4.5 退款交易接口
1.接口功能说明
该接口为接入商家提供交易退款的功能。
2.请求报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 退款填写“REFD” |
| orderNum | String(60) | M | 原交易订单号 |
| refundNum | String(60) | M | 退款订单号:商户自行定义，需保证同一商户号下退款订单号不能重复 |
| returnAmount | String(12) | M | 退款金额：如 100 元，表示为 100 或 100.00 |
| orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | 采用 MD5 签名 |
3.响应报文格式
| 参数 | 类型 | 属性 | 描述 |
| --------- | ---------- | ---- | ---------------------------------------------- |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 退款填写“REFD” |
| refundNum | String(60) | M | 退款订单号 |
| transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| RespCode | String(2) | M | 应答码 00-成功 |
| RespMsg | String(20) | M | 应答消息，全部为英文字符 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | signature |
##### 4.6. 退款查询接口
1.接口说明
该接口为接入商家提供退款查询的功能。
2.请求报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 查询填写“RFQY” |
| refundNum | String(60) | M | 退款订单号 |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | 采用 MD5 签名 |
1. 响应报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000002” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 查询填写“REFD” |
| refundNum | String(60) | M | 退款订单号 |
| transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode | String(2) | M | 应答码 00-成功 |
| RespMsg | String(20) | M | 应答消息，全部为英文字符 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 |
| signType | String(3) | M | MD5 |
| signature | String(32) | M | signature |
#### 5.渠道专属配置
##### 5.1 EB渠道
- 渠道专属配置:
```xml
1.将allpaysdk/WXModule文件夹下的文件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:
<key>NSAppTransportSecurity</key>
<dict> <key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
```
- 消费接口专属字段
请求报文
| 序号 | 名称 | 长度 | 类型 | 参数名称 | 备注 |
| ---- | ---------- | ---- | ---- | ---------------------- | ------------------------------------------------------------ |
| 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. No more than ten digits. |
##### 5.2 WX渠道
- 渠道专属配置:
1. 将allpaysdk/EBModule文件夹下的文件add到项目中
2. 项目设置APPID
商户在微信开放平台申请开发APP应用后，微信开放平台会生成APP的唯一标识APPID。在Xcode中打开项目，设置项目属性中的URL Schemes为您的APPID 如图标红位置所示
1. 导入下面框架和链接库
```objective-c
Security.framework
CoreTelephony.framework
SystemConfiguration.framework
libc++.tbd
libz.tbd
libsqlite3.tbd
```
2. 在“Info.plist”中将要使用的 URL Schemes 列为白名单
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
<string>weixin</string>
</array>
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
```
##### 5.3 APMP渠道
- 消费接口专属字段
请求报文
| Parameter | Type | Required | Description | Sample |
| --------- | ---------- | -------- | ------------------------------------------------------------ | -------------------------------------- |
| timeout | String(10) | O | The default is 12h. Please contact Alipay Technical Support if you need to use other values. Max value is 15d. This parameter controls the valid time from login to completion. | 5m 10m 15m 30m 1h 2h 3h 5h 10h 12h 1d. |
- 渠道专属配置:
1. 将allpaysdk/AliModule文件夹下的文件add到项目中
2. 在Build Phases选项卡的Link Binary With Libraries中，增加以下依赖：
```objective-c
libc++.tbd
libz.tbd
SystemConfiguration.framework
CoreTelephony.framework
QuartzCore.framework
CoreText.framework
CoreGraphics.framework
CFNetwork.framework
CoreMotion. .framework
```
3. 点击项目名称，点击“Info”选项卡，在“URL Types”选项中，点击“+”，在“URL Schemes”中输入alipay, ， 如图标红位置所示
##### 5.3 UP渠道
- 渠道专属配置:
1. 将allpaysdk/UPModule文件夹下的文件add到项目中
2. 导入下面框架和链接库
```objective-c
CFNetwork.framework
SystemConfiguration.framework
libz.tbd
```
3. 在工程info.plist设置中添加一个URL Types回调协议，用于在支付完成后返回商户客户端。请注意URL Schemes需要是唯一的,。 设置的Scheme的值要和支付接口中参数scheme的值相同。
4. 需要在工程对应的plist文件中，添加LSApplicationQueriesSchemes Array并加入uppaysdk、uppaywallet、uppayx1、uppayx2、uppayx3五个item
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
<string>uppaysdk</string>
<string>uppaywallet</string>
<string>uppayx1</string>
<string>uppayx2</string>
<string>uppayx3</string>
</array>
```
5. http请求设置（ats）
在测试环境测试时，需要在工程对应的plist文件中添加NSAppTransportSecurity Dictionary 并同时设置里面NSAllowsArbitraryLoads 属性值为 YES，发生产环境可删除此设置。向Apple发布正式版本时请删除此设置。
##### 5.4 Apple Pay渠道
- 渠道专属配置:
1. 将allpaysdk/AppleModule文件夹下的文件add到项目中
2. xcode 打开 apple pay 功能，如下图
3. 用户 app 判断手机是否支持 Apple Pay 功能,以及是否已加载有可用的支付卡片
```objective-c
//判读方法为：
if([PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks:@[PKPaymentNetworkChinaUnionPay]] )
{
// app 展示 apple pay 支付图标
}
```
#### 6.技术支持
如果您在调试时遇到问题，请我们联系:support@allpayx.com。