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 / 06

Table of Contents:

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

image

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.
"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, 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.
"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, 30, 180, 1800, 3600, 7200, 14400, 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, 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

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, 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.
"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, 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 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