#Android端控件支付产品接口规范文档5.0.0
[上海偶可贝网络科技有限公司](https://www.allpayx.com)
* 版本信息：中文 V5.0.0
* 更新时间：2019 年1 月
#### 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/api/unifiedorder | https://testapi.allpayx.com/api/unifiedorder |
| 查询接口 | https://testapi.allpayx.com/api/orderquery | https://api.allpayx.com/api/orderquery |
| 退款接口 | https://testapi.allpayx.com/api/refund | https://api.allpayx.com/api/refund |
| 退款查询 | https://testapi.allpayx.com/api/refundquery | https://testapi.allpayx.com/api/refundquery |
##### 4.2. 消费交易接口
1.接口说明
商户网关将订单信息发送给 ALLPAY 网关，由 ALLPAY 网关进行处理后将交易流水 号，即 tn，返回给商户网关,tn 作为调起手机 app 支付控件的参数。
2.请求报文格式
下面列举的字段为通用字段，每个渠道都需要上送，部分渠道有渠道专属字段，具体字段请到该渠道的专属渠到字段说明处查看
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000005” |
| 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 | 支付完成后跳转到该地址 |
| backURL | String(400) | 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"}]，需对该字段base64后签名上送 |
| transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| signType | String(3) | M | MD5或SH256 |
| signature | String(32) | M | 采用 MD5或SH256 签名 |
3.响应报文格式
| 参数 | 类型 | 属性 | 描述 |
| -------- | ----------- | ---- | -------------------------------------------------------- |
| RespCode | String(2) | M | 应答码 00-成功 |
| RespMsg | String(100) | M | 应答消息 |
| tn | String(32) | O | 交易流水号，RespCode为“00”时返回,作为调起 sdk 支付的参数 |
4.商户需要提供一个 http/https 协议的接口，包含在参数里传递给 SDK，即 backURL。AllPay
服务器在支付完成后，会以 Post 方式调用 backURL，通知支付结果。商户在接收到通知后，需返回“ok”,
如果没有收到商户返回“OK”,AllPay将会过一段时间后重新推送。时间间隔为[15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400]单位为秒。
参数如下表:
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000005” |
| 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" |
| 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 | 应答消息，全部为英文字符 |
| transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 |
| GWTime | String(14) | M | yyyyMMddHHmmss，为 GW 时间 |
| merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| signType | String(3) | M | MD5或SH256 |
| signature | String(32) | M | 采用 MD5或SH256 签名 |
##### 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.arr 拷贝到项目的libs下面
2. 在Application Module的build.gradle文件的dependencies下添加compile(name: 'allpaysdk', ext: 'aar')
3. 在Application Module的build.gradle文件中添加
```java
repositories {
flatDir {
dirs '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"代表失败,"query"代表 app 需要调用查询接口来确认订单状态
- paymentSchema: 支付渠道, "APMP"代表支付宝, "WX"代表微信
- orderNum: 订单号
- errorDetail: 错误详情
##### 4.4. 查询交易接口
1. 接口说明
该接口为接入商家提供交易查询的功能。
2 .请求报文格式
| 参数 | 类型 | 属性 | 描述 |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version | String(12) | M | 统一填写为“VER000000005” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 查询填写“INQY” |
| orderNum | String(60) | 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 | 统一填写为“VER000000005” |
| 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 | 统一填写为“VER000000005” |
| charSet | String(6) | M | 统一填写为“UTF-8” |
| transType | String(4) | M | 退款填写“REFD” |
| orderNum | String(60) | M | 退款订单号:商户自行定义，需保证同一商户号下退款订单号不能重复 |
| origOrderNum | String(60) | M | 原交易订单号 |
| returnAmount | String(12) | M | 退款金额：如 100 元，表示为 100 或 100.00 |
| orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" |
| merID | String(15) | M | 商户 ID，由AllPay 分配 |
| acqID | String(11) | M | 收单行 ID "99020344" |
| 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” |
| orderNum | 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” |
| orderNum | String(60) | 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 | 查询填写“RFQY” |
| 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 |
#### 5.渠道专属配置
##### 5.1 CA渠道
消费接口专属字段
| 字段名 | 变量名 | 必填 | 类型 | 描述 |
| -------- | --------- | ---- | ---------- | --------- |
| 交易场景 | tradeFrom | M | String(12) | "android" |
#### 6.应答码
| 应答码 | 描 述 |
| ------ | ------------ |
| 00 | 成功 |
| 01 | 失败 |
| 04 | 处理中 |
| 61 | 超过限额 |
| U1 | 商户号不存在 |
| U2 | 签名错误 |
| U3 | 报文被篡改 |
| U4 | 缺失参数 |
| U5 | 无效的参数 |
| U6 | 重复的订单号 |
| U7 | 订单不存在 |
| U8 | 参数不能为空 |
| U9 | 系统错误 |
| P1 | 渠道未配置 |
| P2 | 币种未配置 |
| P3 | 余额不足 |
| P4 | 功能不支持 |
#### 7.技术支持
如果您在调试时遇到问题，请我们联系:support@allpayx.com。