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