#iOS端控件支付产品接口规范文档4.3.1

[上海偶可贝网络科技有限公司](https://www.allpayx.com)

* 版本信息：中文 V4.3.1
* 更新时间：2018 年12 月

#### 1.概述

AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实现快速、安全、集中式的接入支付渠道。

#### 2.交易流程

  ![image](https://git.allpayx.com/OpenAPI/common/raw/master/images/moble_sdk_flowsheet.png)

#### 3. 验签说明

```
1.对于发送到 AllPay 系统的 POST 请求报文，其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。

2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 Key(接入 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.3.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.3.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.3.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 签名                                                |

3.响应报文格式

| 参数          | 类型       | 属性 | 描述                                                         |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version       | String(12) | M    | 统一填写为“VER000000002”                                     |
| charSet       | String(6)  | M    | 统一填写为“UTF-8”                                            |
| transType     | String(4)  | M    | 返回“PURC”                                               |
| 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 签名                                                |

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"                                         |
| 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 如图标红位置所示

  ![image](https://git.allpayx.com/OpenAPI/common/raw/master/images/ios_wx_01.jpg)

3.导入下面框架和链接库

   ```objective-c
   Security.framework
   CoreTelephony.framework
   SystemConfiguration.framework
   libc++.tbd
   libz.tbd
   libsqlite3.tbd
   ```

4.在“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, ， 如图标红位置所示

  ![image](https://git.allpayx.com/OpenAPI/common/raw/master/images/ios_wx_01.jpg)

##### 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 功能，如下图

  ![image](https://git.allpayx.com/OpenAPI/common/raw/master/images/apple_pay_set.png)

3.用户 app 判断手机是否支持 Apple Pay 功能，以及是否已加载有可用的支付卡片 

   ```objective-c
   //判读方法为：
   if([PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks:@[PKPaymentNetworkChinaUnionPay]] )
   {
   // app 展示 apple pay 支付图标 
   }
   ```

#### 6.技术支持

如果您在调试时遇到问题，请与我们联系：support@allpayx.com。