# 移动端H5页面支付接入规范文档V4.3.1
[上海偶可贝网络科技有限公司](https://www.allpayx.com)

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

#### 1.概述

AllPay为基于移动H5页面支付集成云端SDK，以帮助客户实现快速、安全、集中式的接入支付渠道。 

#### 2.交易流程
![image](https://git.allpayx.com/OpenAPI/b2c/raw/master/images/pc_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://www.allpayx.com&charSet=UTF-8&detailInfo=W3siZ29vZHNfbmFtZSI6IuiLueaenCIsInF1YW50aXR5IjoiMyJ9LHsiZ29vZHNfbmFtZSI6IuapmOWtkCIsInF1YW50aXR5IjoiNyJ9XQ==&frontURL=https://www.baidu.com&goodsInfo=apple&merID=000000000000015&merReserve=iPhone&orderAmount=0.01&orderCurrency=USD&orderNum=20190104025014&paymentSchema=APMP&signType=MD5&transTime=20190104025014&transType=PURC&version=VER0000000022f2c77e3718c47cfb47a89a6fbc9d361
```

#### 4.通用API说明 

商户服务器和 AllPay 网关对接的通用接口，每个渠道都具有的功能，包括：消费，查询，退款，退款查询接口。

##### 4.1. 通用API 接入地址 

| 接口名称     | 测试地址                                  | 生产地址                              |
| ------------ | ----------------------------------------- | ------------------------------------- |
| 消费接口     | <https://mchapi.allpayx.com/testjspay>    | <https://mchapi.allpayx.com/jspay>    |
| 交易查询接口 | <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.请求报文格式

下面列举的字段为通用字段，每个渠道都需要上送，部分渠道有渠道专属字段，具体字段请到该渠道的专属渠道字段说明处查看。消费接口分为跳转型和参数返回型，默认为跳转型，参数返回型会在第5章（渠道专属配置）里面说明。

| 参数          | 类型         | 属性 | 描述                                                         |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| 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    | 支付完成后跳转到该地址                                       |
| backURL       | String(400)  | M    | 支付结果异步通知到该地址                                     |
| merReserve    | String(1024) | M    | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 |
| merID         | String(15)   | M    | 商户 ID，由AllPay 分配                                       |
| acqID         | String(11)   | M    | 收单行 ID "99020344"                                         |
| paymentSchema | String(10)   | M    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“                |
| 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 签名                                                |

2.跳转型消费接口响应报文

商户需要提供一个 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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“                |
| 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. 查询交易接口 

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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“                |
| 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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“  |
| 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.4 退款交易接口

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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“                |
| 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.5.  退款查询接口

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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“                |
| 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    | 渠道代码：支付宝 "APMP", 微信 “WX”，银联 “UP“  |
| 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 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。