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

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

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

#### 1.概述
AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实 现快速、安全、集中式的接入支付渠道。
#### 2.交易流程 
  ![image](https://git.allpayx.com/OpenAPI/b2c/raw/master/images/moble_sdk_flowsheet.png)
#### 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. Android 客户端接入步骤 

##### 4.3.1. 接入说明 

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

```java
public static void pay(Activity activity,String tn,boolean mode)
```

::: tip 参数说明
activity —— 用于启动支付控件的活动对象

tn —— 订单信息为交易流水号，即 TN，为商户后台从 AllPay 后台获取

mode —— AllPay 后台环境标识，true 将在 AllPay 正式环境发起交易,false 将在 AllPay 测试环 境发起交易
:::

##### 4.3.2. 添加 SDK 包

1. 把allpaysdk当做Module导入到自己的工程
2. 在Application Module的build.gradle文件的dependencies下添加compile project(':allpaysdk') 
3. 在Application Module的build.gradle文件中添加

```java
repositories {
    flatDir {
        dirs project(':allpaysdk').file('libs')
    }
}
```

##### 4.3.3. 调用支付控件

接着可以通过以下方式调用支付控件:

```java
/**
 * tn——交易流水号，即 TN，为商户后台从 AllPay 后台获取,获取方式参见 AllPay 网关对接文档
 * false 测试环境
 */
AllPayEngine.Pay(ShopCartActivity.this, tn, false);
```

##### 4.3.4. 同步结果通知

支付完成后，获取支付控件支付结果，并添加相应处理逻辑，只需实现调用 Activity 
中的 onActivityResult()方法即可,实例代码如下:

```java
@Override
protected 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 字符串,格式如下:

```text
{
    "state": "cancel",
    "paymentSchema": "UP",
    "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    | 查询填写“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 签名                                                |



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渠道

 消费接口专属字段

- 请求报文

| 序号 | 名称       | 长度 | 类型 | 参数名称               | 备注                                                         |
| ---- | ---------- | ---- | ---- | ---------------------- | ------------------------------------------------------------ |
| 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渠道

- 渠道配置

  在主项目的AndroidManifest.xml文件中添加添加如下配置

```xml
  
  <!-- wpay sdk begin -->


<activity
    android:name="com.allpayx.sdk.wxapi.WXPayEntryActivity"
    android:exported="true"
    android:launchMode="singleTop" />


<activity-alias
    android:name=".wxapi.WXPayEntryActivity"
    android:exported="true"
    android:launchMode="singleTop"
    android:targetActivity="com.allpayx.sdk.wxapi.WXPayEntryActivity" />

<!-- wpay sdk end -->

```

##### 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. |



#### 6.技术支持

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