AllPay_Customs_Integration_Specification_EN.md 16 KB

GoAllPay customs declaration interface specification document V5.0.0

Shanghai GoAllPay Technology Co., Ltd.

  • Version: English V5.0.0
  • Update Time: 2020/07

1. Overview

This document specifies the message interface used for online transactions of customs declaration products between merchants and GoAllPay.

2. Signature rules

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


2. At the end of String1, the signature Key (assigned at 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.


3. Example of signing process: 

String1: IDCard=411422199808080415&acqID=99020344&charSet=UTF-8&customerAccount=ab123456&customs_code=3302462548&customs_name=AAAA&customs_place=CUSTOMSHEADOFFICE&merID=000000000000015&merReserve=dd&name=shi kai feng&orderCurrency=CNY&orderNum=kfvWipRWHEboJPh71m7lXkUILutt&origOrderNum=VzVJhPdX18tDu3vgGfNOIgh71LjY&paymentSchema=UP&productPrice=80&signType=MD5&transTime=20181229171552&transType=DECL&transportPrice=10&version=VER000000005

stringSignTemp: IDCard=411422199808080415&acqID=99020344&charSet=UTF-8&customerAccount=ab123456&customs_code=3302462548&customs_name=AAAA&customs_place=CUSTOMSHEADOFFICE&merID=000000000000015&merReserve=dd&name=shi kai feng&orderCurrency=CNY&orderNum=kfvWipRWHEboJPh71m7lXkUILutt&origOrderNum=VzVJhPdX18tDu3vgGfNOIgh71LjY&paymentSchema=UP&productPrice=80&signType=MD5&transTime=20181229171552&transType=DECL&transportPrice=10&version=VER0000000052f2c77e3718c47cfb47a89a6fbc9d361

signature: 51aebe009a06d79c23524ea18fc2f413

3. API description

Supported request methods including POST and GET, supported parameter formats including form and JSON.

3.1 API list

API Name Test URL Production URL
Declaration https://testapi.allpayx.com/custom/declare https://api.allpayx.com/custom/declare
Declaration Query https://testapi.allpayx.com/custom/query https://api.allpayx.com/custom/query
Declaration Update https://testapi.allpayx.com/custom/update https://api.allpayx.com/custom/update

3.2 Declaration Interface

1. Request parameters

parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes Transaction type: "DECL"
customsDeclarationNo String(60) No The customs declaration order number is defined by the merchant.
Note: Alipay and WeChat can choose to send this field, but UnionPay cannot send this field. If Alipay and WeChat do not send this field, they will use orderNum as the customs declaration order number.
orderNum String(60) Yes Transaction ID: defined by the merchant, it is necessary to ensure that the transaction ID under the same merchant number cannot be repeated.
origOrderNum String(60) Yes Order number for successful payment
productPrice String(12) Yes Commodity amount: such as 100CNY, expressed as 100 or 100.00
transportPrice String(12) Yes Shipping amount:such as 100CNY, expressed as 100 or 100.00
tarPrice String(12) Yes Tariff amount:such as 100CNY, expressed as 100 or 100.00
orderCurrency String(3) Yes Currency of the order: only "CNY"
customs_code String(64) Yes Merchant Customs Record Code
customs_name String(128) Yes Merchant Customs Record Name
customs_place String(128) Yes Customs code, see Annex 1 Customs List for details
name String(64) Yes Consumer name
IDCard String(32) Yes Consumer ID number
customerAccount String(64) Yes Consumer's registered account at the merchant
businessType String(2) No Bonded import: 1
Direct import: 2
If you don’t fill in, the default is 1 Bonded Import.
merID String(15) Yes Merchant ID, assigned by GoAllPay
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
UnionPay:UP
WeChat Pay:WX
Alipay:AP
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature

2. Response parameters

Parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes "DECL"
orderNum String(60) Yes Transaction ID
RespCode String(2) Yes Response Code. "00" stands for success. See Annex 2 for details.
RespMsg String(128) Yes Response Message.
customs_code String(64) Yes Merchant Customs Record Code
customs_name String(128) Yes Merchant Customs Record Name
customs_place String(128) Yes Customs code.
allpayOrderNum String(64) Yes Conversion merchant order number of GoAllPay system.
schemaTransId String(64) Yes The transaction ID of the payment channel.
Note: UnionPay customs declaration needs to use this field as the customs declaration number of the logistics and sales orders.
merID String(15) Yes Merchant ID
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature
originalRequest Object Yes Original customs declaration request
originalResponse Object Yes Original customs declaration response

3.3 Declaration Query Interface

1. Request parameters

Parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes Transaction type: "INQY"
orderNum String(60) Yes Transaction ID
merID String(15) Yes Merchant ID, assigned by GoAllPay.
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
UnionPay:UP
WeChat Pay:WX
Alipay:AP
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature

2. Response parameters

Parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes "DECL"
orderNum String(60) Yes Transaction ID
RespCode String(2) Yes Response Code. "00" stands for success. See Annex 2 for details.
RespMsg String(128) Yes Response Message.
customs_code String(64) Yes Merchant Customs Record Code
customs_name String(128) Yes Merchant Customs Record Name
customs_place String(128) Yes Customs code.
allpayOrderNum String(64) Yes Conversion merchant order number of GoAllPay system.
schemaTransId String(64) Yes The transaction ID of the payment channel.
merID String(15) Yes Merchant ID.
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature

3.4 Declaration Update Interface

1. Request parameters

Parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes Transaction type: "DECL"
customsDeclarationNo String(60) No The customs declaration order number is defined by the merchant.
Note: Alipay and WeChat can choose to send this field, but UnionPay cannot send this field. If Alipay and WeChat do not send this field, they will use orderNum as the customs declaration order number.
orderNum String(60) Yes Transaction ID in the declaration interface.
origOrderNum String(60) Yes Order number for successful payment
productPrice String(12) Yes Commodity amount: such as 100CNY, expressed as 100 or 100.00
transportPrice String(12) Yes Shipping amount:such as 100CNY, expressed as 100 or 100.00
tarPrice String(12) Yes Tariff amount:such as 100CNY, expressed as 100 or 100.00
orderCurrency String(3) Yes Currency of the order: only "CNY"
customs_code String(64) Yes Merchant Customs Record Code
customs_name String(128) Yes Merchant Customs Record Name
customs_place String(128) Yes Customs code, see Annex 1 Customs List for details
name String(64) Yes Consumer name
IDCard String(32) Yes Consumer ID number
customerAccount String(64) Yes Consumer's registered account at the merchant
businessType String(2) No Bonded import: 1
Direct import: 2
If you don’t fill in, the default is 1 Bonded Import.
merID String(15) Yes Merchant ID, assigned by GoAllPay
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
UnionPay:UP
WeChat Pay:WX
Alipay:AP
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature

2. Response parameters

Parameter Type Required Description
version String(12) Yes "VER000000005"
charSet String(6) Yes "UTF-8"
transType String(4) Yes "DECL"
orderNum String(60) Yes Transaction ID
RespCode String(2) Yes Response Code. "00" stands for success. See Annex 2 for details.
RespMsg String(128) Yes Response Message.
customs_code String(64) Yes Merchant Customs Record Code
customs_name String(128) Yes Merchant Customs Record Name
customs_place String(128) Yes Customs code.
allpayOrderNum String(64) Yes Conversion merchant order number of GoAllPay system.
schemaTransId String(64) Yes The transaction ID of the payment channel.
merID String(15) Yes Merchant ID.
acqID String(11) Yes Acquiring Bank ID: "99020344"
paymentSchema String(10) Yes Channel ID.
transTime String(14) Yes Transaction time, format :" yyyyMMddHHmmss"
signType String(10) Yes "MD5" or "SHA256"
signature String(32) Yes MD5 or SHA256 signature

4. Annex 1 Customs List

4.1 Alipay customs list

Customs name Customs code
General Administration of Customs ZONGSHU
Henan Bonded Logistics Center ZHENGZHOU
Ningbo NINGBO
Xinzheng Comprehensive Bonded Zone (Airport) (Push HENAN first, then ZONGSHU) HENAN
Tianjin ZONGSHU
Shanghai SHANGHAI_CBT
Guangzhou (Airport) (Need to fill in the company's filing information in Guangzhou Electronic Port) ZONGSHU
Guangzhou (Nansha) (Need to fill in the company's filing information in Guangzhou Electronic Port) ZONGSHU
Guangzhou (Huangpu) (Need to fill in the company's filing information in Guangzhou Electronic Port) ZONGSHU
Guangzhou (Shatian) (Need to fill in the company's filing information in Guangzhou Electronic Port) ZONGSHU
Hangzhou ZONGSHU

4.2 WeChat Pay customs list

Customs name Customs code
Guangzhou (General Administration Edition) GUANGZHOU_ZS
Guangzhou Huangpu National Inspection (Orders pushed to Huangpu National Inspection need to be pushed to Guangzhou (General Administration version) and Guangzhou Huangpu National Inspection respectively, that is, two customs declaration interfaces need to be requested) GUANGZHOU_HP_GJ
Guangzhou Nansha National Inspection (Orders pushed to Nansha National Inspection need to be pushed to Guangzhou (General Administration version) and Guangzhou Nansha National Inspection respectively, that is, two customs declaration interfaces need to be requested) GUANGZHOU_NS_GJ
Hangzhou (General Administration Edition) HANGZHOU_ZS
Ningbo NINGBO
Zhengzhou (Bonded Logistics Center) ZHENGZHOU_BS
Chongqing CHONGQING
Shanghai (General Administration Edition) SHANGHAI_ZS
Shenzhen SHENZHEN
Zhengzhou Comprehensive Insurance (General Administration Edition) ZHENGZHOU_ZH_ZS
Tianjin (When pushing an order to Tianjin Customs, you need to configure both Tianjin Customs filing information and Tianjin National Inspection filing information in the merchant management background; when calling the customs declaration interface, you only need to push Tianjin Customs, that is, request a customs declaration interface.) TIANJIN

4.3 UnionPay customs list

Customs name Customs code
General Administration of Customs CUSTOMSHEADOFFICE
Shanghai SHANGHAI
Ningbo NINGBO
Hangzhou HANGZHOU
Chongqing CHONGQING
Henan Electronic Port HENAN
Shenzhen SHENZHEN
Fuzhou FUZHOU
Xiamen XIAMEN
Chengdu CHENGDU
Qingdao QINGDAO
Dalian DALIAN

The above list of customs is the customs that supports customs declaration through API for each payment channel. The actual support situation is subject to the update of each payment channel.

5. Annex 2 Response code

RespCode Description
00 Success
01 Fail
04 Processing
61 Exceed the limit
U1 Merchant ID is not exsit
U2 Signature is not correct
U3 Message is tampered
U4 Missing parameter
U5 Invalid parameter
U6 Repeat order number
U7 Order is not exist
U8 Parameter is null
U9 System error
P1 Channel is not setted
P2 Currency is not setted
P5 Channel error
E1 Identity information does not match

*Note: If the response code is 04 when using Unionpay custom declaration, it means the declaration is still processing now. Merchant needs to to call the declaration query API to get the final status later.

6. Technical support

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