|
|
@@ -0,0 +1,245 @@
|
|
|
+#Android端控件支付产品接口规范文档4.0.0
|
|
|
+
|
|
|
+[上海偶可贝网络科技有限公司](https://www.allpayx.com)
|
|
|
+
|
|
|
+* 版本信息：中文 V4.0.0
|
|
|
+* 更新时间：2018 年4 月
|
|
|
+
|
|
|
+#### 1.概述
|
|
|
+AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实 现快速、安全、集中式的接入支付渠道。
|
|
|
+#### 2.交易流程
|
|
|
+ [//]:
|
|
|
+#### 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=http://example.com/example&charSet=UTF- 8&frontURL=nil&merID=000000000000015&merReserve=nil&orderAmount=0.01&orde rCurrency=CNY&orderNum=869873851812&paymentSchema=EB&signType=MD5 &transTime=20151112151356&transType=PURC&version=VER0000000022f2c77e3718c47cfb47a89a6fbc9d361
|
|
|
+```
|
|
|
+#### 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|orderCurrency |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|支付渠道代码 |2 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;Easebuzz:"EB"
|
|
|
+ 13|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss"
|
|
|
+ 14|签名类型 |3 |文本|signType |MD5
|
|
|
+ 15|签名 |3 |文本|signature |采用 MD5 签名
|
|
|
+
|
|
|
+3. 响应报文格式
|
|
|
+
|
|
|
+ 序号 |名称 |类型|长度|参数名称|备注
|
|
|
+ -----|-----|----|----|------|------
|
|
|
+ 1|交易流水号 |32|文本|tn |tn 作为调起 sdk 支付的参数
|
|
|
+
|
|
|
+#### 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|支付渠道代码 |2 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;Easebuzz:"EB"
|
|
|
+ 9|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss"
|
|
|
+ 10|签名类型 |3 |文本|signType |MD5
|
|
|
+ 11|签名 |3 |文本|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|签名 |3 |文本|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|orderCurrency |3|文本|orderCurrency |人民币填写“CNY”,美元填写"USD"
|
|
|
+ 7|商户预留字段 |1024 |文本|merReserve |商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。
|
|
|
+ 8|商户代码 |15 |文本|merID |商户 ID，由AllPay 分配
|
|
|
+ 9|收单行 ID |11 |文本|acqID |收单行 ID "99020344"
|
|
|
+ 10|支付渠道代码 |2 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;Easebuzz:"EB"
|
|
|
+ 11|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss"
|
|
|
+ 12|签名类型 |3 |文本|signType |MD5
|
|
|
+ 13|签名 |3 |文本|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|签名 |3 |文本|signature |采用 MD5 签名
|
|
|
+
|
|
|
+#### 4.ANDROID 客户端接入步骤
|
|
|
+
|
|
|
+#### 4.1. 接入说明
|
|
|
+
|
|
|
+```
|
|
|
+启动支付控件的接口，接口定义如下:
|
|
|
+
|
|
|
+public static void pay(Activity activity,String tn,boolean mode)
|
|
|
+
|
|
|
+参数说明:
|
|
|
+
|
|
|
+activity —— 用于启动支付控件的活动对象
|
|
|
+
|
|
|
+tn——订单信息为交易流水号，即 TN，为商户后台从 AllPay 后台获取
|
|
|
+
|
|
|
+mode ——AllPay 后台环境标识，true 将在 AllPay 正式环境发起交易,false 将在 AllPay 测试环 境发起交易
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+#### 4.2. 添加 SDK 包
|
|
|
+
|
|
|
+
|
|
|
+#### 4.3. 调用支付控件
|
|
|
+```
|
|
|
+接着可以通过以下方式调用支付控件:
|
|
|
+//tn——交易流水号，即 TN，为商户后台从 AllPay 后台获取,获取方式参见 AllPay 网关对接文档
|
|
|
+AllPayEngine.Pay(ShopCartActivity.this, tn,false);//false 测试环境
|
|
|
+```
|
|
|
+#### 4.4. 同步结果通知
|
|
|
+
|
|
|
+ ```
|
|
|
+ 支付完成后，获取支付控件支付结果，并添加相应处理逻辑，只需实现调用 Activity
|
|
|
+中的 onActivityResult()方法即可,实例代码如下:
|
|
|
+
|
|
|
+@Overrideprotected void onActivityResult(int requestCode, int resultCode, Intent data)
|
|
|
+{
|
|
|
+if (data == null) {
|
|
|
+return;
|
|
|
+}
|
|
|
+
|
|
|
+if (requestCode == AllPayConst.VTPAY_PAY_REQUESR_CODE&& resultCode == AllPayConst.VTPAY_PAY_RESULT_CODE) {
|
|
|
+String result = data.getExtras().getString("pay_result"); }
|
|
|
+}
|
|
|
+
|
|
|
+pay_result,为 json 字符串,格式如下:
|
|
|
+ {
|
|
|
+"state": "cancel",
|
|
|
+"paymentSchema": "UP",
|
|
|
+"orderNum": "604337497032",
|
|
|
+"errorDetail": "user cancel operation "
|
|
|
+}
|
|
|
+
|
|
|
+报文说明:
|
|
|
+
|
|
|
+state: "success"代表成功, "cancel"代表用户取消操作,"fail"代表失败,"query"代表 app 需要调用查询接口来确认订单状态
|
|
|
+paymentSchema:支付渠道, "APMP"代表支付宝, "WX"代表微信
|
|
|
+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|orderCurrency |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|支付渠道代码 |2 |文本|paymentSchema |支付宝:"APMP"; 微信:"WX"; 境外银联:"UP"; ApplePay 支付:"APP" ;Easebuzz:"EB"
|
|
|
+ 15|交易应答码 |2 |文本|RespCode |应答码 00-成功
|
|
|
+ 16|应答文字信息 |20 |文本|RespMsg |应答消息，全部为英文字符
|
|
|
+ 17|交易时间 |14 |文本|transTime |交易时间,格式:"yyyyMMddHHmmss"
|
|
|
+ 18|GW 处理时间 |14 |文本|GWTime |YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间
|
|
|
+ 19|签名类型 |3 |文本|signType |MD5
|
|
|
+ 20|签名 |3 |文本|signature |采用 MD5 签名
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
