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

* Version:English V5.0.0
* Update Time:2019/04

## 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 encryption 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=20190104022800&paymentSchema=AP&signType=MD5&transTime=20190104022800&transType=PURC&version=VER0000000052f2c77e3718c47cfb47a89a6fbc9d361
```
## 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://testapi.allpayx.com/api/unifiedorder | https://api.allpayx.com/api/unifiedorder |
| Inquiry | https://testapi.allpayx.com/api/orderquery   | https://api.allpayx.com/api/orderquery   |
| Refund    | https://testapi.allpayx.com/api/refund       | https://api.allpayx.com/api/refund       |
| Refund inquiry | https://testapi.allpayx.com/api/refundquery  | https://api.allpayx.com/api/refundquery  |

### 4.2 Purchase interface

1.Interface specification

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

2.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 5 channels (exclusive) inside.

| Parameter          | Type         | Required | Description                                        |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version       | String(12)   | M    | “VER000000005”                                     |
| 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                                     |
| 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/common/src/master/paymentSchema.md) |
| 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 :" yyyyMMddHHmmss"                               |
| merReserve    | String(1024) | O    | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| signType      | String(10)   | M    | "MD5" or "SHA256"                                                   |
| signature     | String(32)   | M    | MD5 or SHA256 signature                                         |

3.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 POST, informing the payment result. When merchant receive the notification, the merchant is required to return "OK".

  If we didn't receive "OK" from merchant，AllPay will resend the response message to merchant.Time interval is[15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second.

Parameters as follows:

| parameter          | Type         | Required | Description          |
| ------------- | ------------ | ---- | ------------------------------------------------------------ |
| version       | String(12)   | M    | "VER000000005"                                     |
| 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"        |
| 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/common/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                                                     |
| transID       | String(32)   | M    | The unique transaction id generated by the gateway.                       |
| GWTime        | String(14)   | M    | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time.                                   |
| transTime     | String(14)   | M    | Transaction time, format :" yyyyMMddHHmmss"                             |
| merReserve    | String(1024) | O    | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| signType      | String(10)   | M    | "MD5" or "SHA256"                                                  |
| signature     | String(32)   | M    | MD5 or SHA256 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    | "VER000000005"                                     |
| charSet       | String(6)  | M    | "UTF-8"                                            |
| transType     | String(4)  | M    | "INQY"                                             |
| orderNum      | String(60) | M    | Original trade order number                                                       |
| 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/common/src/master/paymentSchema.md) |
| transTime     | String(14) | M    | Transaction time, format :" yyyyMMddHHmmss"                               |
| signType      | String(10) | M    | "MD5" or "SHA256"                                                          |
| signature     | String(32) | M    | MD5 or SHA256 signature                                                |

3.Response message format

| Parameter          | Type       | Required | Description                                         |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version       | String(12) | M    | "VER000000005"                                     |
| charSet       | String(6)  | M    | "UTF-8"                                            |
| transType     | String(4)  | M    | "INQY"                                               |
| 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/common/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 :" yyyyMMddHHmmss"                             |
| GWTime        | String(14) | M    | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time               |
| signType      | String(3)  | M    | "MD5" or "SHA256"                                                  |
| signature     | String(32) | M    | MD5 or SHA256 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    | "VER000000005"                                     |
| charSet       | String(6)  | M    | "UTF-8"                                            |
| transType     | String(4)  | M    | "REFD"                                               |
| orderNum      | 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 |
| origOrderNum  | String(60) | M    | Original trade order number                                                 |
| 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"          |
| merID         | String(15) | M    | Merchant ID, assigned by AllPay                                       |
| paymentSchema | String(10) | M    | Channel code:[Click Here](https://git.allpayx.com/OpenAPI/common/src/master/paymentSchema.md) |
| acqID         | String(11) | M    | "99020344"                                         |
| transTime     | String(14) | M    | Transaction time, format :" yyyyMMddHHmmss"                             |
| signType      | String(3)  | M    | "MD5" or "SHA256"                                                  |
| signature     | String(32) | M    | MD5 or SHA256 signature                                        |

3.Response message format

| Parameter      | Type       | Required | Description                                           |
| --------- | ---------- | ---- | ---------------------------------------------- |
| version   | String(12) | M    | "VER000000005"                       |
| charSet   | String(6)  | M    | "UTF-8"                              |
| transType | String(4)  | M    | "REFD"                                 |
| orderNum  | 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) | M    | Channel code：[Click Here](https://git.allpayx.com/OpenAPI/common/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 :" yyyyMMddHHmmss"                 |
| GWTime    | String(14) | M    | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| signType  | String(10) | M    | "MD5" or "SHA256"                                  |
| signature | String(32) | M    | MD5 or SHA256 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    | "VER000000005"                                     |
| charSet       | String(6)  | M    | "UTF-8"                                            |
| transType     | String(4)  | M    | "RFQY"                                               |
| orderNum      | String(60) | M    | Refund order number                                                   |
| 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/common/src/master/paymentSchema.md) |
| transTime     | String(14) | M    | Transaction time, format :" yyyyMMddHHmmss"                               |
| signType      | String(10) | M    | "MD5" or "SHA256"                                                           |
| signature     | String(32) | M    | MD5 or SHA256 signature                                                |

3.Response message format

| Parameter          | Type       | Required | Description                                         |
| ------------- | ---------- | ---- | ------------------------------------------------------------ |
| version       | String(12) | M    | "VER000000005"                                     |
| charSet       | String(6)  | M    | "UTF-8"                                           |
| transType     | String(4)  | M    | "RFQY"                                               |
| orderNum      | 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) | M    | Channel code:[Click Here](https://git.allpayx.com/OpenAPI/common/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 :" yyyyMMddHHmmss"                             |
| GWTime        | String(14) | M    | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time               |
| signType      | String(10) | M    | "MD5" or "SHA256"                                                  |
| signature     | String(32) | M    | MD5 or SHA256 signature                                        |

## 5.Channel exclusive allocation

### 5.1 WX

#### 5.1.1 QR code no jump mode

 This mode returns the URL value of WeChat payment collection for parameter return, ask the merchant to convert it into QR code, generate the front interface of payment, and prompt the user to scan the code to pay.

 Purchase interface specific fields

| Parameter      | Type   | Required | Description     |
| --------- | ------ | ---- | -------- |
| tradeFrom | String | M    | "QRCODE" |

Response message:

| Parameter     | Type   | Required | Description                            |
| -------- | ------ | ---- | ------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                       |
| RespMsg  | String | M    | Response message        |
| code_url | String | O    | Characters to generate QR code. When RespCode=00 returns it. |

#### 5.1.2 QR code jump mode

It's jump mode, open the front-end page provided by AllPay, which contains WeChat QR code.

 Purchase interface specific fields

| Parameter      | Type   | Required | Description    |
| --------- | ------ | ---- | ------- |
| tradeFrom | String | M    | "QUICK" |

#### 5.1.3 WeChat Official Accounts payment

 Purchase interface specific fields

| Parameter      | Type   | Required | Description    |
| --------- | ------ | ---- | ------- |
| tradeFrom | String | M    | "JSAPI" |

#### 5.1.4 WeChat Mini Programs payment

 Purchase interface specific fields

| Parameter      | Type   | Required | Description       |
| --------- | ------ | ---- | ---------- |
| tradeFrom | String | M    | "APPLET"   |
| openid    | String | M    | Wechat openid |

Response message:

| Parameter       | Type   | Required | Description                                                   |
| ---------- | ------ | ---- | ------------------------------------------------------ |
| RespCode   | String | M    | 00 stands for success; 01 stands for fail.                                         |
| RespMsg    | String | M    | Response message                                               |
| sdk_params | String | O    | Required parameter for Mini Program payment(JSON). When RespCode=00 returns it. |

Parameter sdk_params is used to call up the WeChat Mini Programs payment. Please refer to the Mini Programs integration specification.

#### 5.1.5 APP mode

 Purchase interface specific fields

| Parameter      | Type   | Required | Description  |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "APP" |

Response message:

| Parameter     | Type   | Required | Description                                                      |
| -------- | ------ | ---- | --------------------------------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                                 |
| RespMsg  | String | M    | Response message                                                  |
| tn       | String | O    | Transaction serial number. Required parameter for Wechat app payment. When RespCode=00 returns it. |

After getting tn, call the SDK to pay according to Section 7 of this document.

### 5.2 AP

#### 5.2.1 WebSite mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description  |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "WEB" |

### 5.3 APMP

#### 5.3.1 H5 mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ------- |
| tradeFrom | String | M    | "JSAPI" |

#### 5.3.2 APP mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "APP" |

Response message：

| Parameter | Type   | Required | Description |
| -------- | ------ | ---- | --------------------------------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                                 |
| RespMsg  | String | M    | Response message                                                  |
| tn       | String | O    | Transaction serial number. Required parameter for Wechat app payment. When RespCode=00 returns it. |

After getting tn, call the SDK to pay according to Section 7 of this document.

#### 5.3.3 QR code no jump mode

 This mode returns the URL value of WeChat payment collection for parameter return, ask the merchant to convert it into QR code, generate the front interface of payment, and prompt the user to scan the code to pay.

 Purchase interface specific fields

| Parameter      | Type   | Required | Description     |
| --------- | ------ | ---- | -------- |
| tradeFrom | String | M    | "QRCODE" |

Response message:

| Parameter     | Type   | Required | Description                            |
| -------- | ------ | ---- | ------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                       |
| RespMsg  | String | M    | Response message        |
| code_url | String | O    | Characters to generate QR code. When RespCode=00 returns it. |

### 5.4 UP

#### 5.4.1 H5 mode, adaptive PC and mobile

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ---- |
| tradeFrom | String | M    | "H5" |

#### 5.4.2 APP mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "APP" |

Response message：

| Parameter | Type   | Required | Description |
| -------- | ------ | ---- | --------------------------------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                                 |
| RespMsg  | String | M    | Response message                                                  |
| tn       | String | O    | Transaction serial number. Required parameter for Wechat app payment. When RespCode=00 returns it. |

After getting tn, call the SDK to pay according to Section 7 of this document.

```javascript
Test cards:

Credit Card: 5200831111111113
Mobile: 13552535506
CVN2: 123
Exp Date: month 11 year 19
SMS Code on PC: 111111
SMS Code on Mobile: 123456

Credit Card: 6226388000000095
Mobile: 18100000000
CVN2: 248
Exp Date: month 12 year 19
SMS Code on PC: 111111
SMS Code on Mobile: 123456
```

### 5.5 Apple Pay

#### 5.5.1 APP mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "APP" |

Response message：

| Parameter | Type   | Required | Description |
| -------- | ------ | ---- | --------------------------------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail.                                 |
| RespMsg  | String | M    | Response message                                                  |
| tn       | String | O    | Transaction serial number. Required parameter for Wechat app payment. When RespCode=00 returns it. |

After getting tn, call the SDK to pay according to Section 7 of this document.

### 5.6 CA

#### 5.6.1 APP mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description  |
| --------- | ------ | ---- | ----- |
| tradeFrom | String | M    | "APP" |

Response message:

| Parameter | Type   | Required | Description                                          |
| -------- | ------ | ---- | --------------------------------------------------------- |
| RespCode | String | M    | 00 stands for success; 01 stands for fail. |
| RespMsg  | String | M    | Response message |
| tn       | String | O    | Transaction serial number. Required parameter for CA app payment. When RespCode=00 returns it.|

 After you get tn，please integrate according to [Android Integration Specification](https://git.allpayx.com/OpenAPI/common/src/master/v5/android/Android_Integration_Specification_EN.md)

### 5.7 MIPAY

#### 5.7.1 H5 mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| ---------- | ------ | ---- | ------------------------------------------------------------ |
| tradeFrom  | String | M    | "H5"                                                         |
| firstname  | String | M    | This is name of the customer who is doing the transaction.   |
| email      | String | M    | this is email id of the customer who is doing transaction    |
| phone      | String | M    | Phone number of the customer                                 |
| customerId | String | O    | Customer ID, when client register on merchant, merchant distribute it to client. |

```javascript
Test environment configuration：

Modify the test machine hosts file, add the following two information.
114.80.87.249 account.preview.n.xiaomi.net
114.80.87.249 api.account.preview.n.xiaomi.net

Test card：

Card number：5123456789012346
Validity period：0520
cvv：123
```

### 5.8 EB

#### 5.8.1 H5 mode

 Purchase interface specific fields

| Parameter | Type   | Required | Description |
| --------- | ------ | ---- | ---------------------------------------------------------- |
| tradeFrom | String | M    | "H5"                                                       |
| firstname | String | M    | This is name of the customer who is doing the transaction. |
| email     | String | M    | this is email id of the customer who is doing transaction  |
| phone     | String | M    | Phone number of the customer                               |

## 6.RespCode 

| RespCode | Description      |
| ------ | --------- |
| 00     | Success       |
| 01     | Fail       |
| 04     | Processing     |
| 61     | Exceed the limit   |
| U1     | Merchant ID is not exsit |
| U2     | Signature is not correct   |
| U3     | Message is tampered |
| U4     | Missing parameter   |
| U5     | Invalid parameter |
| U6     | Repeat order number |
| U7     | Order is not exist  |
| U8     | Parameter is null   |
| U9     | System error   |
| P1     | Channel is not setted  |
| P2     | Currency is not setted  |
| P3     | Balance is not enough    |
| P4     | Function is not supported  |
| P5     | Channel returns "Error"  |

## 7.APP mode integration specification

Android Integration Specification:[Click Here](https://git.allpayx.com/OpenAPI/common/src/master/v5/android/Android_Integration_Specification_EN.md)

iOS Integration Specification:[Click Here](https://git.allpayx.com/OpenAPI/common/src/master/v5/ios/iOS_Integration_Specification_EN.md)

## 8.Technical support

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