# HTML5 Integration Specification V4.3.1
[Shanghai AllPay Technology Co., Ltd.](https://www.allpayx.com)

* Version:English V4.3.1
* Update Time:12 2018


#### 1.Overview

AllPay provides customers with unified API access to help them implement fast, secure and centralized access payment channels.

#### 2.Transaction process 

![image](https://git.allpayx.com/OpenAPI/b2c/raw/master/images/pc_flowsheet.png)

#### 3. Description of verifying the signature  

```
1.For a POST request message sent to the AllPay system, in which all incoming parameters (except signature parameters) according to the field name of ASCII smallest sequence (dictionary), using the format of the URL key/value pair (key1 = value1 & key2 = value2... ) spliced into a string String1.

2.At the end of String1, the signature Key (assigned at AllPay upon access) agreed by both parties is spliced directly (no need to connect with "&"), resulting in a stringSignTemp string, and an md5 operation on stringSignTemp to get the value of signature.

3.Sample signature string: 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. Common interface

Common interface includes notification, asynchronous notification of transactions, transaction inquiry, refund, refund inquiry interface.

##### 4.1. General API access address

| Interface Name | Test URL                                  | Production URL                        |
| -------------- | ----------------------------------------- | ------------------------------------- |
| Purchase       | <https://mchapi.allpayx.com/testjspay>    | <https://mchapi.allpayx.com/jspay>    |
| Inquiry        | <https://testapi.allpayx.com/pay>         | <https://api.allpayx.com/pay>         |
| Refund         | <https://testapi.allpayx.com/refund>      | <https://api.allpayx.com/refund>      |
| Refund inquiry | <https://testapi.allpayx.com/refundquery> | <https://api.allpayx.com/refundquery> |

##### 4.2. Purchase interface

1.Request message format

This field is a list of common fields, sending, every channel needs some channel channel exclusive field, specific fields please go to the channel's exclusive canal to the fields that view. Consumer interface is divided into jump transformation and parameters return type, default to jump transformation, parameters return type will be explained in chapter 4 channels (exclusive) inside.

| Parameter     | Type         | Required | Description                                                  |
| ------------- | ------------ | -------- | ------------------------------------------------------------ |
| version       | String(12)   | M        | "VER000000002"                                               |
| charSet       | String(6)    | M        | “UTF-8”                                                      |
| transType     | String(4)    | M        | “PURC”                                                       |
| orderNum      | String(60)   | M        | Order number: it is defined by the merchant itself, and the order number must not be repeated for the same merchant number |
| orderAmount   | String(12)   | M        | Order amount: if 100 yuan, it will be 100 or 100.00          |
| orderCurrency | String(3)    | M        | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| frontURL      | String(400)  | M        | When the payment is complete, jump to the address            |
| backURL       | String(400)  | M        | Payment results are asynchronously notified to this address  |
| merReserve    | String(1024) | M        | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| merID         | String(15)   | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11)   | M        | "99020344"                                                   |
| paymentSchema | String(10)   | M        | For WeChat, that will be “WX”. For UnionPay, that will be “UP”. For Alipay, that will be “APMP”; |
| goodsInfo     | String(60)   | M        | Commodity information, displayed on the payment page         |
| detailInfo    | String(400)  | M        | Product details format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], which requires base-64 encoding of this field before signing and sending. |
| transTime     | String(14)   | M        | Transaction time, format :" yyymmddhhmmss"                   |
| signType      | String(3)    | M        | MD5                                                          |
| signature     | String(32)   | M        | MD5 signature                                                |

2.Jump transformation Purchase interface response message

The merchant needs to provide an HTTP/HTTPS protocol interface that is included in the parameters passed to the SDK, the backURL. After the payment is complete, the AllPay server will call the backURL as a Get, informing the payment result. 

| Parameter     | Type         | Required | Description                                                  |
| ------------- | ------------ | -------- | ------------------------------------------------------------ |
| version       | String(12)   | M        | "VER000000002"                                               |
| charSet       | String(6)    | M        | “UTF-8”                                                      |
| transType     | String(4)    | M        | “PURC”                                                       |
| orderNum      | String(60)   | M        | Order number                                                       |
| orderAmount   | String(12)   | M        | Order amount: if 100 yuan, it will be 100 or 100.00          |
| orderCurrency | String(3)    | M        | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| settAmount    | String(12)   | M        | 100 is displayed as 100 or 100.00                            |
| settCurrency  | String(3)    | M        | Comply with ISO standards                                    |
| rate          | String(7)    | M        | Real exchange rate, 7 digits                                 |
| merReserve    | String(1024) | M        | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| transID       | String(32)   | M        | The unique transaction id generated by the gateway.          |
| merID         | String(15)   | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11)   | M        | "99020344"                                                   |
| paymentSchema | String(10)   | M        | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode      | String(2)    | M        | 00 stands for success; 01 stands for fail.                   |
| RespMsg       | String(20)   | M        | Response message, all English characters                     |
| transTime     | String(14)   | M        | Transaction time, format :" yyymmddhhmmss"                   |
| GWTime        | String(14)   | M        | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time|
| signType      | String(3)    | M        | MD5                                                          |
| signature     | String(32)   | M        | MD5 signature                                                |

##### 4.3. Inqiury interface 

1.Interface specification

 This interface provides the function of inqiury transaction for access merchants.

2.Request message format 

| Parameter     | Type         | Required | Description                                                  |
| ------------- | ------------ | -------- | ------------------------------------------------------------ |
| version       | String(12)   | M        | "VER000000002"                                               |
| charSet       | String(6)    | M        | "UTF-8"                                                      |
| transType     | String(4)    | M        | "INQY"                                                       |
| orderNum      | String(60)   | M        | Original trade order number                                  |
| merReserve    | String(1024) | M        | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| merID         | String(15)   | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11)   | M        | "99020344"                                                   |
| paymentSchema | String(10)   | M        | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime     | String(14)   | M        | Transaction time, format :" yyymmddhhmmss"                   |
| signType      | String(3)    | M        | "MD5"                                                        |
| signature     | String(32)   | M        | MD5 signature                                                |

3.Response message format

| Parameter     | Type       | Required | Description                                                  |
| ------------- | ---------- | -------- | ------------------------------------------------------------ |
| version       | String(12) | M        | "VER000000002"                                               |
| charSet       | String(6)  | M        | “UTF-8”                                                      |
| transType     | String(4)  | M        | “PURC”                                                       |
| orderNum      | String(60) | M        | Original trade order number                                  |
| transID       | String(32) | M        | The unique transaction id generated by the gateway.          |
| merID         | String(15) | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11) | M        | "99020344"                                                   |
| paymentSchema | String(10) | M        | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode      | String(2)  | M        | 00 stands for success; 01 stands for fail.                   |
| RespMsg       | String(20) | M        | Response message, all English characters                     |
| transTime     | String(14) | M        | Transaction time, format :" yyymmddhhmmss"                   |
| GWTime        | String(14) | M        | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| signType      | String(3)  | M        | MD5                                                          |
| signature     | String(32) | M        | signature                                                    |

##### 4.4. Refund interface

1.Interface specification 

This interface provides the function of refund transaction for access merchants. 

2.Request message format 

| Parameter     | Type         | Required | Description                                                  |
| ------------- | ------------ | -------- | ------------------------------------------------------------ |
| version       | String(12)   | M        | “VER000000002”                                               |
| charSet       | String(6)    | M        | “UTF-8”                                                      |
| transType     | String(4)    | M        | “REFD”                                                       |
| orderNum      | String(60)   | M        | Original trade order number                                  |
| refundNum     | String(60)   | M        | Refund order number: it is defined by the merchant, and the refund order number under the same merchant number cannot be repeated |
| returnAmount  | String(12)   | M        | Refund amount: if 100 yuan, it is 100 or 100.00              |
| orderCurrency | String(3)    | M        | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| merReserve    | String(1024) | M        | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| merID         | String(15)   | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11)   | M        | "99020344"                                                   |
| paymentSchema | String(10)   | M        | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime     | String(14)   | M        | Transaction time, format :" yyymmddhhmmss"                   |
| signType      | String(3)    | M        | MD5                                                          |
| signature     | String(32)   | M        | signature                                                    |

3.Response message format

| Parameter | Type       | Required | Description                                                  |
| --------- | ---------- | -------- | ------------------------------------------------------------ |
| version   | String(12) | M        | “VER000000002”                                               |
| charSet   | String(6)  | M        | “UTF-8”                                                      |
| transType | String(4)  | M        | “REFD”                                                       |
| refundNum | String(60) | M        | The merchant shall define it by itself, and the refund number of the same merchant number shall not be repeated |
| transID   | String(32) | M        | The unique transaction id generated by the gateway.          |
| merID     | String(15) | M        | Merchant ID, assigned by AllPay                              |
| acqID     | String(11) | M        | "99020344"                                                   |
| RespCode  | String(2)  | M        | 00 stands for success; 01 stands for fail.                   |
| RespMsg   | String(20) | M        | Response message, all English characters                     |
| transTime | String(14) | M        | Transaction time, format :" yyymmddhhmmss"                   |
| GWTime    | String(14) | M        | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| signType  | String(3)  | M        | MD5                                                          |
| signature | String(32) | M        | signature                                                    |

##### 4.5. Refund Inqiury interface

1.Interface specification

 This interface provides the function of Refund inqiury transaction for access merchants.

2.Request message format 

| Parameter     | Type         | Required | Description                                                  |
| ------------- | ------------ | -------- | ------------------------------------------------------------ |
| version       | String(12)   | M        | “VER000000002”                                               |
| charSet       | String(6)    | M        | “UTF-8”                                                      |
| transType     | String(4)    | M        | “RFQY”                                                       |
| refundNum     | String(60)   | M        | Refund order number                                          |
| merReserve    | String(1024) | M        | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| merID         | String(15)   | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11)   | M        | "99020344"                                                   |
| paymentSchema | String(10)   | M        | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| transTime     | String(14)   | M        | Transaction time, format :" yyymmddhhmmss"                   |
| signType      | String(3)    | M        | MD5                                                          |
| signature     | String(32)   | M        | signature                                                    |

3.Response message format

| Parameter     | Type       | Required | Description                                                  |
| ------------- | ---------- | -------- | ------------------------------------------------------------ |
| version       | String(12) | M        | “VER000000002”                                               |
| charSet       | String(6)  | M        | “UTF-8”                                                      |
| transType     | String(4)  | M        | “REFD”                                                       |
| refundNum     | String(60) | M        | Refund order number                                          |
| transID       | String(32) | M        | The unique transaction id generated by the gateway.          |
| merID         | String(15) | M        | Merchant ID, assigned by AllPay                              |
| acqID         | String(11) | M        | "99020344"                                                   |
| paymentSchema | String(10) |          | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) |
| RespCode      | String(2)  | M        | Response message, all English characters                     |
| RespMsg       | String(20) | M        | Response message, all English characters                     |
| transTime     | String(14) | M        | Transaction time, format :" yyymmddhhmmss"                   |
| GWTime        | String(14) | M        | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| signType      | String(3)  | M        | MD5                                                          |
| signature     | String(32) | M        | signature                                                    |

#### 5.Channel exclusive allocation

##### 5.1 AP

| 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.Technical support

If you have problems with debugging, please contact us: support@allpayx.com