AllPay_Integration_Specification_EN.md 67 KB
GoAllPay Integration Specification V5.2.3
Shanghai GoAllPay Technology Co., Ltd.
- Version: English V5.2.3
- Update Time: 2022 / 11
Table of Contents:
- 1. Overview
- 2. API description
- 3. Online Payment API
- 4. Token Payment API
- 4.1 Apply Token
- 4.2 Apply token result notification - callback
- 4.3 Apply token status query
- 4.4 Token payment
- 4.5 Token update
- 4.6 Merchant cancel token
- 4.7 User cancel token ( Alipay+ )
- 4.8 Token payment result notification - callback
- 4.9 Token payment query
- 4.10 Token payment refund
- 4.11 User cancel token result notification - callback ( Alipay+ )
- 4.12 Check token status
- 5. RespCode
- 6. APP mode integration specification
- 7. Technical support
1. Overview
GoAllPay provides customers with unified API access to help them implement fast, secure and centralized access payment channels.
2. API description
2.1 Transaction process
2.2 Signature rules
1. For the request message sent to the GoAllPay system, in which all incoming parameters (except parameter signature) 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 GoAllPay 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 (The encryption algorithm is subject to the parameter "signType" value).
3. Example of signing process:
string1: OsType=IOS&OsVersion=&acqID=99020344&backURL=https://testapi.allpayx.com/test&charSet=UTF-8&detailInfo=W3siZ29vZHNfbmFtZSI6ICJhcHBsZSIsICJxdWFudGl0eSI6ICIyIn1d&frontURL=http://example.com&goodsInfo=apple&logisticsStreet=上海市浦东新区xx路xx号xxx室&merID=merchant_id&merReserve=&orderAmount=1&orderCurrency=CNY&orderNum=20220620171733&paymentSchema=UP&signType=SHA256&tradeFrom=H5&transTime=20220620171733&transType=PURC&userID=user01&userIP=114.91.1.243&version=VER000000005
stringSignTemp: OsType=IOS&OsVersion=&acqID=99020344&backURL=https://testapi.allpayx.com/test&charSet=UTF-8&detailInfo=W3siZ29vZHNfbmFtZSI6ICJhcHBsZSIsICJxdWFudGl0eSI6ICIyIn1d&frontURL=http://example.com&goodsInfo=apple&logisticsStreet=上海市浦东新区xx路xx号xxx室&merID=merchant_id&merReserve=&orderAmount=1&orderCurrency=CNY&orderNum=20220620171733&paymentSchema=UP&signType=SHA256&tradeFrom=H5&transTime=20220620171733&transType=PURC&userID=user01&userIP=114.91.1.243&version=VER000000005key
signature: 40f1e5adebba58cc7822dac0b3a2bfebb6676e245370be027cdfb952695bee29
2.3 General description
Request method: POST
Message format: JSON
Test environment host: https://testapi.allpayx.com
Production environment host: https://api.allpayx.com
3. Online Payment API
3.1 Payment
1. Interface specification
This interface provides the function of purchase transaction for access merchants.
2. Request path
/api/createorder
3. Request parameters
It consists of general fields and channel exclusive fields. All upload fields must be signed.
Channel exclusive fields: Click to view
General fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| paymentSchema | String(10) | Yes | Channel ID:Click Here |
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PURC" |
| orderNum | String(60) | Yes | 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) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", US dollar filling in "USD" |
| frontURL | String(400) | Yes | When the payment is complete, redirect to the URL with GET method and 3.3 Payment result notification - callback parameters. |
| backURL | String(400) | Yes | Payment results are asynchronously notified to this URL. After the payment is successful, the GoAllPay server will call the backURL by POST JSON method to notify the payment result (See 3.3 Payment result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| goodsInfo | String(60) | Yes | Commodity information. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| detailInfo | String(400) | Yes | Product details. Format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], and required Base64 encoding before incoming. Note: "goods_name" can't include special symbols, such as "#", "&", "+", etc. |
| transTime | String(14) | Yes | Transaction time. Format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Reserved content, customized by the merchant. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
| OsType | String(20) | Yes | OS type. Options: "IOS", "ANDROID", "WINDOWS", "MAC", "OTHER" |
| OsVersion | String(20) | No | OS version. Example: "10.0.19043" |
| userIP | String(20) | Yes | User IP |
| userID | String(20) | Yes | The user's unique ID at the merchant. |
| logisticsAddress | String(200) | Yes | Shipping address. If it is a virtual item, fill in the user's email. |
4. Response parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| RespCode | String(2) | Yes | Response code. 00 stands for success. |
| RespMsg | String(256) | Yes | Response message |
| merID | String(15) | No | Merchant ID. |
| orderNum | String(60) | No | Order number. |
| transID | String(32) | No | GoAllPay serial number. |
| parameter | Object | No | Payment parameters. Returned when RespCode is 00 and not background mode payment. For details, please visit Channel exclusive fields |
3.2 Cashier payment
1. Interface specification
This interface provides WEB cashier payment function for access merchants, and currently mainly supports international credit cards. This interface uniformly encapsulates international card payment and 3DS functions of different brands, improving the efficiency and experience of merchants accessing payment.
2. Request path
/api/createcashier
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| paymentSchema | String(10) | Yes | "FC" |
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PURC" |
| orderNum | String(60) | Yes | 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) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", US dollar filling in "USD" |
| frontURL | String(400) | Yes | When the payment is complete, redirect to the URL with GET method and 3.3 Payment result notification - callback parameters. |
| backURL | String(400) | Yes | Payment results are asynchronously notified to this URL. After the payment is successful, the GoAllPay server will call the backURL by POST JSON method to notify the payment result (See 3.3 Payment result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| goodsInfo | String(60) | Yes | Commodity information. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| detailInfo | String(400) | Yes | Product details. Format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], and required Base64 encoding before incoming. Note: "goods_name" can't include special symbols, such as "#", "&", "+", etc. |
| transTime | String(14) | Yes | Transaction time. Format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Reserved content, customized by the merchant. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
| tradeFrom | String | Yes | "H5" |
| OsType | String(20) | Yes | OS type. Options: "IOS", "ANDROID", "WINDOWS", "MAC", "OTHER" |
| OsVersion | String(20) | No | OS version. Example: "10.0.19043" |
| userIP | String(20) | Yes | User IP |
| userID | String(20) | Yes | The user's unique ID at the merchant. |
| logisticsAddress | String(200) | Yes | Shipping address. If it is a virtual item, fill in the user's email. |
| timeout | String(5) | No | Timeout seconds. The minimum value is 60 seconds. If the value is less than 60 seconds or is not specified, the default value is 1800 seconds. Example: "300" means 300 seconds. |
Order logistics information, international card payment methods of some channels are required, please communicate with the support staff for details.
| Parameter | Type | Required | Description |
|---|---|---|---|
| logisticsCountry | String(2) | No | Logistics country/region, 2-digit country code, such as: US |
| logisticsState | String | No | Logistics state/province/state, 2-digit code, such as: CA |
| logisticsCity | String | No | Logistics city |
| logisticsStreet | String | No | Logistics address |
| logisticsPostalCode | String | No | Logistics zip code |
| logisticsEmail | String | No | Logistics email |
| logisticsPhone | String | No | Logistics phone |
| logisticsHouseNo | String | No | Logistics house number or name |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| RespCode | String(2) | Yes | Response code. 00 stands for success. |
| RespMsg | String(256) | Yes | Response message |
| merID | String(15) | No | Merchant ID. |
| orderNum | String(60) | No | Order number. |
| transID | String(32) | No | GoAllPay serial number. |
| parameter | Object | No | Payment parameters. Returned when RespCode is 00, and value is "payUrl" object. |
3.3 Payment result notification - callback
1. Interface specification
The merchant calls payment or cashier payment or background payment or pre-authorization, the result will be returned to the backURL of the transaction through this interface.
2. Request path
"backURL" parameter
3. Request parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | Payment: "PURC"; Pre-authorization: "PAUT" |
| orderNum | String(60) | Yes | Order number |
| orderAmount | String(12) | Yes | Order amount |
| orderCurrency | String(3) | Yes | Currency of the order |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | Response code. 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transID | String(32) | Yes | GoAllPay serial number. |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Merchant reserved content. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
String "OK"
3.4 Inqiury
1. Interface specification
This interface provides the function of inqiury transaction for access merchants.
2. Request path
/api/orderquery
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "INQY" |
| orderNum | String(60) | Yes | Order number |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID：Click Here |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | Transaction type |
| orderNum | String(60) | Yes | Order number |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
3.5 Refund
1. Interface specification
This interface provides access to merchants with a refund of transactions.
(1) Interface supplement
- The interface is initiated after the consumer transaction is successful, and the original order number is required to be specified.
- Under normal circumstances, the refund amount of the merchant on the day shall not be greater than the successful transaction amount on the day.
- CIL and RDP international credit card transactions cannot be refunded on the same day, can be revoked, and can only be refunded every other day.
- RevPay does not support online refunds, please contact support staff for refunds.
(2) Interface transaction process
2. Request path
/api/refund
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "REFD" |
| orderNum | String(60) | Yes | 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) | Yes | Original trade order number |
| returnAmount | String(12) | Yes | Refund amount: if 100CNY, it is 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| paymentSchema | String(10) | Yes | Channel ID:Click Here |
| acqID | String(11) | Yes | "99020344" |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
| backURL | String(400) | Yes | Refund results are asynchronously notified to this URL. After the refund is successful, the GoAllPay server will call the backURL by POST JSON method to notify the refund result (See Refund result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "REFD" |
| orderNum | String(60) | Yes | Refund order number |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
5. Refund result notification - callback
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "REFD" |
| orderNum | String(60) | Yes | Refund order number |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
| returnAmount | String(12) | Yes | Refund amount |
| orderCurrency | String(3) | Yes | Currency of the order |
3.6 Pre-authorization
1. Interface specification
The pre-authorization interface is applicable to foreign card (including VISA, MasterCard, JCB and other card brands) and UnionPay card transactions. Pre-authorized transactions will not participate in liquidation, and the issuing bank will temporarily freeze user funds.
2. Request path
/api/createorder
3. Request parameters
It consists of general fields and channel exclusive fields. All upload fields must be signed.
Channel exclusive fields: Click to view
General fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PAUT" |
| orderNum | String(60) | Yes | 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) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", US dollar filling in "USD" |
| frontURL | String(400) | Yes | When the payment is complete, redirect to the URL with GET method and 3.3 Payment result notification - callback parameters. |
| backURL | String(400) | Yes | Payment results are asynchronously notified to this URL. After the payment is successful, the GoAllPay server will call the backURL by POST JSON method to notify the payment result (See 3.3 Payment result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID: Click Here |
| goodsInfo | String(60) | Yes | Commodity information. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| detailInfo | String(400) | Yes | Product details. Format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], and required Base64 encoding before incoming. Note: "goods_name" can't include special symbols, such as "#", "&", "+", etc. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Reserved content, customized by the merchant. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| RespCode | String(2) | Yes | Response code. 00 stands for success. |
| RespMsg | String(256) | Yes | Response message |
| merID | String(15) | No | Merchant ID. |
| orderNum | String(60) | No | Order number. |
| transID | String(32) | No | GoAllPay serial number. |
| parameter | Object | No | Payment parameters. Return it when RespCode is 00. |
3.7 Pre-authorization completion interface
1. Interface specification
The pre-authorization completion interface is applicable to foreign card (including VISA, MasterCard, JCB and other card brands) and UnionPay card transactions. The pre-authorized transaction is similar to the consumer transaction. After the transaction is successful, the merchant will be cleared of funds.
(1) Interface supplement
- The interface is initiated after the pre-authorization transaction is successful, and the original pre-authorization order number is required to be specified, and the time is separated by no more than 30 days.
- The pre-authorization completion transaction amount cannot be greater than the pre-authorized transaction amount.
- Pre-authorized transactions that only support one successful pre-authorization completion transaction.
(2) Interface transaction process
2. Request path
/api/pauc
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PAUC" |
| orderNum | String(60) | Yes | Order number: it is defined by the merchant itself, and the order number must not be repeated for the same merchant number |
| origOrderNum | String(60) | Yes | Pre-authorized order number |
| orderAmount | String(12) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", US dollar filling in "USD" |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID: Click Here |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PAUC" |
| orderNum | String(60) | Yes | Order number |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
3.8 Cancellation interface
1. Interface specification
The revocation interface is applicable to foreign cards (including VISA, MasterCard, JCB and other card brands), UnionPay cards and Alipay Philippines wallet.
(1) Interface supplement
- This interface supports external card consumption, pre-authorization, and pre-authorization to complete transactions, UnionPay pre-authorization transactions, and Alipay Filipino wallet consumer transaction cancellation.
- When withdrawing consumption, you can only support the cancellation of the day's trading (note: For CIL international card, after 23:00 Beijing time, it is considered the next day. For RDP international card, after 24:00 Beijing time, it is considered the next day.). For non-day trading, it can be processed through the refund interface.
(2) Interface transaction process
2. Request path
/api/canc
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "VOID" |
| orderNum | String(60) | Yes | Order number: it is defined by the merchant itself, and the order number must not be repeated for the same merchant number |
| origOrderNum | String(60) | Yes | Original transaction order number: The order number to be revoked, which can be consumption, pre-authorization, pre-authorization completed orderNum |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID: Click Here |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "VOID" |
| orderNum | String(60) | Yes | Order number of cancellation |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Token Payment API
4.1 Apply Token
4.1.1 Apply token ( Alipay+ )
1. Interface specification
Provide apply token function. Applicable to Alipay+.
Interface transaction process:
2. Request path
/api/applyToken
3. Request parameters
Channel exclusive fields: Click to view
General fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| userRegion | String(2) | No | User country or region, ISO standard two-digit country code, such as "PH" |
| orderNum | String(60) | Yes | Order number: it is defined by the merchant itself, and the order number must not be repeated for the same merchant number |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| customerId | String(60) | Yes | User ID: Defined by the merchant, and ensure that different users can not be duplicated under the same merchant number. |
| frontURL | String(400) | Yes | When the apply token is complete, redirect to the URL with GET method and 4.2 Apply token result notification - callback parameters. |
| backURL | String(400) | Yes | Apply token results are asynchronously notified to this URL. After the apply token is successful, the GoAllPay server will call the backURL by POST JSON method to notify the apply token result (See 4.2 Apply token result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| paymentSchema | String(10) | Yes | Channel ID: "AliPayPlus" or "FC" |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| terminalType | String(10) | Yes | Terminal type. Choose one of "WEB", "WAP", "MINI_APP", "APP" |
| OsType | String(20) | Yes | OS type. Options: "IOS", "ANDROID", "WINDOWS", "MAC", "OTHER" |
| OsVersion | String(20) | No | OS version. Example: "10.0.19043" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| RespCode | String(2) | Yes | Response code. 00 stands for success. |
| RespMsg | String(256) | Yes | Response message |
| merID | String(15) | No | Merchant ID. |
| orderNum | String(60) | No | Order number. |
| transID | String(32) | No | GoAllPay serial number. |
| parameter | Object | No | Apply token parameters. Return it when RespCode is 00. |
4.1.2 Apply token and payment ( International card )
1. Interface specification
Provide apply token and payment function. Applicable to international card.
Interface transaction process:
2. Request path
/api/createcashier
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| paymentSchema | String(10) | Yes | "FC" |
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PURC" |
| orderNum | String(60) | Yes | 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) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", US dollar filling in "USD" |
| frontURL | String(400) | Yes | When the payment is complete, redirect to the URL with GET method and 3.3 Payment result notification - callback parameters. |
| backURL | String(400) | Yes | Payment results are asynchronously notified to this URL. After the payment is successful, the GoAllPay server will call the backURL by POST JSON method to notify the payment result (See 3.3 Payment result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| goodsInfo | String(60) | Yes | Commodity information. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| detailInfo | String(400) | Yes | Product details. Format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], and required Base64 encoding before incoming. Note: "goods_name" can't include special symbols, such as "#", "&", "+", etc. |
| transTime | String(14) | Yes | Transaction time. Format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Reserved content, customized by the merchant. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
| tradeFrom | String | Yes | "H5" |
| OsType | String(20) | Yes | OS type. Options: "IOS", "ANDROID", "WINDOWS", "MAC", "OTHER" |
| OsVersion | String(20) | No | OS version. Example: "10.0.19043" |
| customerId | String(60) | Yes | User ID: Defined by the merchant, and ensure that different users can not be duplicated under the same merchant number. |
| tokenFlag | String(10) | Yes | Whether to return the token of the contract payment token at the same time. When you need to return, fill in "true". This feature requires separate approval to activate. |
| tokenBackURL | String(400) | Yes | The asynchronous notification URL of the contracted payment token. When tokenFlag is "true", it must be filled in. |
| userIP | String(20) | Yes | User IP |
| userID | String(20) | Yes | The user's unique ID at the merchant. |
Order logistics information, international card payment methods of some channels are required, please communicate with the support staff for details.
| Parameter | Type | Required | Description |
|---|---|---|---|
| logisticsCountry | String(2) | No | Logistics country/region, 2-digit country code, such as: US |
| logisticsState | String | No | Logistics state/province/state, 2-digit code, such as: CA |
| logisticsCity | String | No | Logistics city |
| logisticsStreet | String | No | Logistics address |
| logisticsPostalCode | String | No | Logistics zip code |
| logisticsEmail | String | No | Logistics email |
| logisticsPhone | String | No | Logistics phone |
| logisticsHouseNo | String | No | Logistics house number or name |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| RespCode | String(2) | Yes | Response code. 00 stands for success. |
| RespMsg | String(256) | Yes | Response message |
| merID | String(15) | No | Merchant ID. |
| orderNum | String(60) | No | Order number. |
| transID | String(32) | No | GoAllPay serial number. |
| parameter | Object | No | Payment parameters. Returned when RespCode is 00, and value is "payUrl" object. |
4.2 Apply token result notification - callback
1. Interface specification
The apply token result will be returned through this interface.
2. Request path
- Alipay+ :
backURL - International card:
tokenBackURL
3. Request parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Order number |
| token | String(32) | No | Token payment use it. |
| tokenExpiryTime | String(25) | No | Token expiry time. Format: "2019-11-27T12:01:01+08:00" |
| refreshToken | String(32) | No | Update token use it. |
| refreshTokenExpiryTime | String(25) | No | refreshToken expiry time. Format: "2019-11-27T12:01:01+08:00" |
| merID | String(15) | Yes | Merchant ID |
| paymentSchema | String(10) | Yes | Channel ID |
| sub_brand_code | String(20) | No | Sub brand code |
| RespCode | String(2) | Yes | Response code. 00 stands for success; 01 stands for fail. See Chapter 5 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| customerId | String(60) | Yes | User ID |
| transID | String(32) | Yes | GoAllPay serial number. |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
String "OK"
4.3 Apply token status query
1. Interface specification
Check whether the apply token is successful.
2. Request path
/api/inquiryToken
3. Request parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Apply token order number |
| merID | String(15) | Yes | Merchant ID |
| paymentSchema | String(20) | Yes | Channel ID："AliPayPlus" or "FC" |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Order number |
| token | String(32) | No | Token payment use it. |
| tokenExpiryTime | String(25) | No | Token expiry time. Format: "2019-11-27T12:01:01+08:00" |
| refreshToken | String(32) | No | Update token use it. |
| refreshTokenExpiryTime | String(25) | No | refreshToken expiry time. Format: "2019-11-27T12:01:01+08:00" |
| merID | String(15) | Yes | Merchant ID |
| paymentSchema | String(10) | Yes | Channel ID |
| sub_brand_code | String(20) | No | Sub brand code |
| RespCode | String(2) | Yes | Response code. 00 stands for success; 01 stands for fail. See Chapter 5 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| customerId | String(60) | Yes | User ID |
| transID | String(32) | Yes | GoAllPay serial number. |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4.4 Token payment
1. Interface specification
Token payment, according to the token returned during apply token.
Interface transaction process:
2. Request path
/api/bindPay
3. Request parameters
It consists of general fields and channel exclusive fields. All upload fields must be signed.
Channel exclusive fields: Click to view
General fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PURC" |
| orderNum | String(60) | Yes | 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) | Yes | Order amount: if 100CNY, it will be 100 or 100.00 |
| orderCurrency | String(3) | Yes | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
| backURL | String(400) | Yes | Payment results are asynchronously notified to this URL. After the payment is successful, the GoAllPay server will call the backURL by POST JSON method to notify the payment result (See 3.3 Payment result notification - callback for details). When merchant receive the notification, it is required to response String "OK". If we didn't receive "OK" from merchant，GoAllPay will resend the response message to merchant.Time interval is [15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400], the unit is second. |
| customerId | String(60) | Yes | User ID: It is defined by the merchant, and it cannot be repeated under the same merchant number. |
| token | String(32) | Yes | The token returned during apply token. |
| merID | String(15) | Yes | Merchant ID, assigned by GoAllPay |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(20) | Yes | Channel ID："AliPayPlus" or "FC" |
| goodsInfo | String(60) | Yes | Commodity information. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| detailInfo | String(400) | Yes | Product details. Format: [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}], and required Base64 encoding before incoming. Note: "goods_name" can't include special symbols, such as "#", "&", "+", etc. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| tradeFrom | String(20) | Yes | "PAN-BINGDING" |
| merReserve | String(1024) | No | Reserved content, customized by the merchant. Note: Don't include special symbols, such as "#", "&", "+", etc. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "PURC" |
| orderNum | String(60) | Yes | Order number |
| orderAmount | String(12) | Yes | Order amount |
| orderCurrency | String(3) | Yes | Currency of the order |
| merID | String(15) | Yes | Merchant ID |
| acqID | String(11) | Yes | "99020344" |
| paymentSchema | String(10) | Yes | Channel ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 6 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| reason | JSON Object | 否 | Fail reason, JSON format{"code":"reason code", "text":"reason description"}, Click to view。When the reason code is INVALID_TOKEN and EXPIRED_ACCESS_TOKEN, mean the token is invalid, and the merchant can call the /api/refreshToken interface to update the token and try again. |
| transID | String(32) | Yes | GoAllPay serial number. |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| merReserve | String(1024) | No | Merchant reserved content. |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4.5 Token update
1. Interface specification
Merchants need to actively update the token before the token expires. Otherwise, when make token payment, the user will be required to re-authorize.
Interface transaction process:
2. Request path
/api/refreshToken
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| customerId | String(60) | Yes | User ID |
| orderNum | String(60) | Yes | Order number: it is defined by the merchant itself, and the order number must not be repeated for the same merchant number |
| merID | String(15) | Yes | Merchant ID |
| refreshToken | String(32) | Yes | refreshToken returned during apply token |
| sub_brand_code | String(20) | No | Sub brand code. Required when paymentSchema is "AliPayPlus" |
| paymentSchema | String(20) | Yes | Channel ID："AliPayPlus" or "FC" |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Order number |
| token | String(32) | No | Token payment use it. |
| tokenExpiryTime | String(25) | No | Token expiry time. Format: "2019-11-27T12:01:01+08:00" |
| refreshToken | String(32) | No | Update token use it. |
| refreshTokenExpiryTime | String(25) | No | refreshToken expiry time. Format: "2019-11-27T12:01:01+08:00" |
| merID | String(15) | Yes | Merchant ID |
| paymentSchema | String(10) | Yes | Channel ID |
| sub_brand_code | String(20) | No | Sub brand code |
| RespCode | String(2) | Yes | Response code. 00 stands for success; 01 stands for fail. See Chapter 5 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| reason | JSON Object | No | Fail reason，JSON format{"code":"reason code", "text":"reason description"}, Click to view |
| customerId | String(60) | Yes | User ID |
| transID | String(32) | Yes | GoAllPay serial number. |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time. |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4.6 Merchant cancel token
1. Interface specification
Merchant cancel token.
Interface transaction process:
2. Request path
/api/cancelToken
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| customerId | String(60) | Yes | User ID |
| token | String(32) | Yes | The token returned during apply token. |
| orderNum | String(60) | Yes | Cancel token order number |
| merID | String(15) | Yes | Merchant ID |
| sub_brand_code | String(20) | No | Sub brand code. Required when paymentSchema is "AliPayPlus" |
| paymentSchema | String(20) | Yes | Channel ID："AliPayPlus" or "FC" |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Cancel token order number |
| transID | String(32) | Yes | GoAllPay serial number. |
| merID | String(15) | Yes | Merchant ID |
| paymentSchema | String(10) | Yes | Channel ID |
| sub_brand_code | String(20) | No | Sub brand code |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 5 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| token | String(32) | No | token |
| customerId | String(60) | Yes | User ID |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| GWTime | String(14) | Yes | yyyyMMddHHmmss this should be a GWtime, currently is local transaction time |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4.7 User cancel token ( Alipay+ )
1. Interface specification
User cancel token in wallet, GoAllPay pushes the result to the merchant, and the merchant responds. Applicable to Alipay+.
Interface transaction process:
2. Request path
Merchant domain+/api/consultUnbinding
Note: Merchant needs to manually provide Merchant domain to Goallpay for configuration.
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| customerId | String(60) | Yes | User ID |
| token | String(32) | Yes | The token returned during apply token. |
| merID | String(15) | Yes | Merchant ID |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| allowUnbinding | String(10) | Yes | agree: true; refuse: false |
| refuseReason | String(60) | No | When allowUnbinding is false, fill in the reason |
4.8 Token payment result notification - callback
After the token payment is successful, backURL will receive the payment result notification pushed by the GoAllPay system. See 3.3 Payment result notification - callback for details.
4.9 Token payment query
Query the token payment result by calling 3.4 Inqiury
4.10 Token payment refund
Refund the token payment by calling 3.5 Refund. Valid for 1 year.
4.11 User cancel token result notification - callback ( Alipay+ )
1. Interface specification
For some wallets, such as Alipay_CN, when the user cancel token in the wallet, the merchant does not need to confirm. After GoAllPay receives the cancel token notice from the wallet, it will notify the merchant. Merchant needs to reply OK after receiving it. Applicable to Alipay+.
2. Request path
Merchant domain+/api/notifyUnbound
Note: Merchant needs to manually provide Merchant domain to Goallpay for configuration.
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| customerId | String(60) | Yes | User ID |
| token | String(32) | Yes | The token returned during apply token. |
| merID | String(15) | Yes | Merchant ID |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
4. Response parameters
String "OK"
4.12 Check token status
1. Request path
/api/checkToken
2. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| customerId | String(60) | Yes | User ID |
| token | String(32) | Yes | The token returned during apply token. |
| merID | String(15) | Yes | Merchant ID |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | "SHA256" |
| signature | String(32) | Yes | signature |
3. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | String(32) | No | token |
| tokenExpiryTime | String(25) | No | Token expiry time. |
| merID | String(15) | Yes | Merchant ID |
| RespCode | String(2) | Yes | 00 stands for success; 01 stands for fail. See Chapter 5 Response Codes in this document for details. |
| RespMsg | String(20) | Yes | Response message |
| status | String(20) | Yes | normal, invalid, non-existent |
| customerId | String(60) | Yes | User ID |
| transTime | String(14) | Yes | Transaction time, format: "yyyyMMddHHmmss" |
| signType | String(10) | Yes | SHA256 |
| signature | String(32) | Yes | Signature |
5. RespCode
| RespCode | Description |
|---|---|
| 00 | Success |
| 01 | Fail |
| 04 | Processing |
| 61 | Exceed the limit |
| U1 | Merchant ID is not exist |
| U2 | Signature error |
| 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" |
| A3 | Channel merchant is not exist |
6. APP mode integration specification
Android Integration Specification:Click Here
iOS Integration Specification:Click Here
7. Technical support
If you have problems with debugging, please contact us: support@allpayx.com