AllPay_Integration_Specification_EN.md 59 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. Authorization Payment API
- 4.1 Authorization
- 4.2 Authorization result notification - callback
- 4.3 Authorization status query
- 4.4 Authorization payment
- 4.5 Authorization update
- 4.6 Merchant initiate deauthorization
- 4.7 User initiate deauthorization
- 4.8 Authorization payment result notification - callback
- 4.9 Authorization payment query
- 4.10 Authorization payment refund
- 4.11 User deauthorization result notification - callback
- 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, 15, 30, 180, 1800, 3600, 7200, 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. "IOS", "ANDROID", "HARMONYOS", "WINDOWS", "MAC", "OTHER". Choose one of them. |
| 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. |
| logisticsStreet | 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, 15, 30, 180, 1800, 3600, 7200, 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. "IOS", "ANDROID", "HARMONYOS", "WINDOWS", "MAC", "OTHER". Choose one of them. |
| OsVersion | String(20) | No | OS version. Example: "10.0.19043" |
| tokenFlag | String(10) | No | 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) | No | 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. |
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.
- International credit card transactions cannot be refunded on the same day, can be revoked, and can only be refunded every other day.
- Under normal circumstances, the refund amount of the merchant on the day shall not be greater than the successful transaction amount on the day.
(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, 15, 30, 180, 1800, 3600, 7200, 14400], the unit is second. |
4. 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, 15, 30, 180, 1800, 3600, 7200, 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 |
3.9 Manual refund application interface
1. Interface specification
To refund the payments which are more than 90 days ago, the merchant can't process the online refund interface, but need to call the interface to initiate the refund application. After the application is successful, our business staff will handle it manually. The processing period is about 3 to 5 working days. The refund application transaction will be successfully refunded after manual processing, and the transaction will be liquidated.
2. Request path
/api/refdreq
3. Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "REFDREQ" |
| 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 |
4. Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| charSet | String(6) | Yes | "UTF-8" |
| transType | String(10) | Yes | "REFDREQ" |
| 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 means the application has been accepted |
| 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. Authorization Payment API
4.1 Authorization
1. Interface specification
Provide authorization function.
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: It is defined by the merchant, and it cannot be repeated under the same merchant number. |
| frontURL | String(400) | Yes | When the authorization is complete, redirect to the URL with GET method and 4.2 Authorization result notification - callback parameters. |
| backURL | String(400) | Yes | Authorization results are asynchronously notified to this URL. After the authorization is successful, the GoAllPay server will call the backURL by POST JSON method to notify the authorization result (See 4.2 Authorization 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, 15, 30, 180, 1800, 3600, 7200, 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. "IOS", "ANDROID", "HARMONYOS", "WINDOWS", "MAC", "OTHER". Choose one of them. |
| 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 | Authorization parameters. Return it when RespCode is 00. |
4.2 Authorization result notification - callback
1. Interface specification
The merchant calls authorization, the result will be returned through this interface.
2. Request path
"backURL" or "tokenBackURL" parameter
3. Request parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| orderNum | String(60) | Yes | Order number |
| token | String(32) | No | Authorization 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 Authorization status query
1. Interface specification
Check whether the authorization is successful.
2. Request path
/api/inquiryToken
3. Request parameters
| parameter | Type | Required | Description |
|---|---|---|---|
| version | String(12) | Yes | "VER000000005" |
| customerId | String(60) | Yes | User ID |
| orderNum | String(60) | Yes | Authorization 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 | Order number |
| token | String(32) | No | Authorization 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 Authorization payment
1. Interface specification
Authorization payment, according to the token returned during authorization.
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, 15, 30, 180, 1800, 3600, 7200, 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 authorization. |
| 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 Authorization update
1. Interface specification
Merchants need to actively update the token before the token expires. Otherwise, when make authorization 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 authorization |
| 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 | Authorization 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 initiate deauthorization
1. Interface specification
Merchant initiate deauthorization.
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 authorization. |
| orderNum | String(60) | Yes | Deauthorization 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 | Deauthorization 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 initiate deauthorization
1. Interface specification
User initiate deauthorization in wallet, GoAllPay pushes the result to the merchant, and the merchant responds.
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 authorization. |
| 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 Authorization payment result notification - callback
After the authorized 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 Authorization payment query
Query the Authorization payment result by calling 3.4 Inqiury
4.10 Authorization payment refund
Refund the Authorization payment by calling 3.5 Refund. Valid for 1 year.
4.11 User deauthorization result notification - callback
1. Interface specification
For some wallets, such as Alipay_CN, when the user deauthorizes in the wallet, the merchant does not need to confirm. After GoAllPay receives the deauthorization notice from the wallet, it will notify the merchant. Merchant needs to reply OK after receiving it.
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 authorization. |
| 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"
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