OpenAPI/b2c_ios_sdk: b2c_ios_sdk

b2c_ios_sdk

tao.zhou bccc6f35c1 更新 'README.md'		5 years ago
Demo	f2008989b6 更新文档	5 years ago
.gitignore	b277a1d16b 删除EB渠道	5 years ago
README.md	bccc6f35c1 更新 'README.md'	5 years ago

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

上海偶可贝网络科技有限公司

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

1.概述

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

2.交易流程

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	渠道代码：点击查看详情
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	渠道代码：点击这里
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. 接入说明

启动支付控件的接口，接口定义如下:

[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" 并添加如下方法

-(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 同步结果通知

[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	渠道代码：点击这里
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	渠道代码：点击这里
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	渠道代码：点击这里
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	渠道代码：点击这里
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	渠道代码：点击这里
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渠道

渠道专属配置:

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

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

   Security.framework
   CoreTelephony.framework
   SystemConfiguration.framework
   libc++.tbd
   libz.tbd
   libsqlite3.tbd

4.在“Info.plist”中将要使用的 URL Schemes 列为白名单

   <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中，增加以下依赖：

   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.导入下面框架和链接库

   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

   <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 功能，以及是否已加载有可用的支付卡片

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

6.技术支持

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

README.md

1.概述

2.交易流程

3. 验签说明

4.通用API说明

4.1. 通用API 接入地址

4.2. 消费交易接口

4.3. iOS 客户端接入步骤

4.3.1. 接入说明

4.3.2. 添加 SDK 包

4.3.3 同步结果通知

4.4. 查询交易接口

4.5 退款交易接口

4.6. 退款查询接口

5.渠道专属配置

5.1 EB渠道

5.2 WX渠道

5.3 APMP渠道

5.3 UP渠道

5.4 Apple Pay渠道

6.技术支持