|
|
@@ -0,0 +1,248 @@
|
|
|
+# GoAllPay customs declaration interface specification document V5.0.0
|
|
|
+[Shanghai GoAllPay Technology Co., Ltd.](https://www.goallpayx.com)
|
|
|
+
|
|
|
+* 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.Description of verifying the signature
|
|
|
+
|
|
|
+```
|
|
|
+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.Sample signature string: 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
|
|
|
+```
|
|
|
+
|
|
|
+## 3.API description
|
|
|
+
|
|
|
+Customs declaration-related interfaces that the merchant server and GoAllPay gateway connect, including declaration, declaration query, and declaration update.
|
|
|
+
|
|
|
+### 3.1 General API access address
|
|
|
+
|
|
|
+| Interface 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 message format**
|
|
|
+
|
|
|
+| parameter | Type | Required | Description |
|
|
|
+| --------------- | ----------- | ---- | ------------------------------------------------------------ |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | Transaction type: "DECL" |
|
|
|
+| customsDeclarationNo | String(60) | O | The customs declaration order number is defined by the merchant. <br>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) | M | 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) | M | Order number for successful payment |
|
|
|
+| productPrice | String(12) | M | Commodity amount: such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| transportPrice | String(12) | M | Shipping amount：such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| tarPrice | String(12) | M | Tariff amount：such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| orderCurrency | String(3) | M | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
|
|
|
+| customs_code | String(64) | M | Customs record code |
|
|
|
+| customs_name | String(128) | M | Customs record name |
|
|
|
+| customs_place | String(128) | M | Customs code, see Annex 1 Customs List for details |
|
|
|
+| name | String(64) | M | Consumer name |
|
|
|
+| IDCard | String(32) | M | Consumer ID number |
|
|
|
+| customerAccount | String(64) | M | Consumer's registered account at the merchant |
|
|
|
+| businessType | String(2) | O | Bonded import: 1<br>Direct import: 2<br>If you don’t fill in, the default is 1 Bonded Import. |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+**2.Response message format**
|
|
|
+
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
+| -------------- | ----------- | ---- | --------------------------------------------- |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | "DECL" |
|
|
|
+| orderNum | String(60) | M | Transaction ID |
|
|
|
+| RespCode | String(2) | M | Response Code. "00" stands for success. See Annex 2 for details. |
|
|
|
+| RespMsg | String(128) | M | Response Message. |
|
|
|
+| customs_code | String(64) | M | Customs record code |
|
|
|
+| customs_name | String(128) | M | Customs record name |
|
|
|
+| customs_place | String(128) | M | Customs code, see Annex 1 Customs List for details. |
|
|
|
+| allpayOrderNum | String(64) | M | Conversion merchant order number of GoAllPay system. |
|
|
|
+| schemaTransId | String(64) | M | The transaction ID of the payment channel.<br/>Note: UnionPay customs declaration needs to use this field as the customs declaration number of the logistics and sales orders. |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+### 3.3 Declaration Query Interface
|
|
|
+
|
|
|
+**1.Request message format**
|
|
|
+
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
+| ------------- | ---------- | ---- | --------------------------------------------- |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | Transaction type: "INQY" |
|
|
|
+| orderNum | String(60) | M | Transaction ID |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay. |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+**2.Response message format**
|
|
|
+
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
+| ------------- | ----------- | ---- | --------------------- |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | "DECL"|
|
|
|
+| orderNum | String(60) | M | Transaction ID |
|
|
|
+| RespCode | String(2) | M | Response Code. "00" stands for success. See Annex 2 for details. |
|
|
|
+| RespMsg | String(128) | M | Response Message. |
|
|
|
+| customs_code | String(64) | M | Customs record code |
|
|
|
+| customs_name | String(128) | M | Customs record name |
|
|
|
+| customs_place | String(128) | M | Customs code, see Annex 1 Customs List for details. |
|
|
|
+| allpayOrderNum | String(64) | M | Conversion merchant order number of GoAllPay system. |
|
|
|
+| schemaTransId | String(64) | M | The transaction ID of the payment channel. |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay. |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+### 3.4 Declaration Update Interface
|
|
|
+
|
|
|
+**1.Request message format**
|
|
|
+
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
+| ----------- | ----------- | ---- | ----------- |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | Transaction type: "DECL" |
|
|
|
+| customsDeclarationNo | String(60) | O | The customs declaration order number is defined by the merchant. <br>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) | M | Transaction ID in the declaration interface. |
|
|
|
+| origOrderNum | String(60) | M | Order number for successful payment |
|
|
|
+| productPrice | String(12) | M | Commodity amount: such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| transportPrice | String(12) | M | Shipping amount：such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| tarPrice | String(12) | M | Tariff amount：such as 100 yuan, expressed as 100 or 100.00 |
|
|
|
+| orderCurrency | String(3) | M | Currency of the order: ISO standard, such as RMB filling in "CNY", us dollar filling in "USD" |
|
|
|
+| customs_code | String(64) | M | Customs record code |
|
|
|
+| customs_name | String(128) | M | Customs record name |
|
|
|
+| customs_place | String(128) | M | Customs code, see Annex 1 Customs List for details |
|
|
|
+| name | String(64) | M | Consumer name |
|
|
|
+| IDCard | String(32) | M | Consumer ID number |
|
|
|
+| customerAccount | String(64) | M | Consumer's registered account at the merchant |
|
|
|
+| businessType | String(2) | O | Bonded import: 1<br>Direct import: 2<br>If you don’t fill in, the default is 1 Bonded Import. |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+**2.Response message format**
|
|
|
+
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
+| -------------- | ----------- | ---- | -------------------------- |
|
|
|
+| version | String(12) | M | "VER000000005" |
|
|
|
+| charSet | String(6) | M | "UTF-8" |
|
|
|
+| transType | String(4) | M | "DECL" |
|
|
|
+| orderNum | String(60) | M | Transaction ID |
|
|
|
+| RespCode | String(2) | M | Response Code. "00" stands for success. See Annex 2 for details. |
|
|
|
+| RespMsg | String(128) | M | Response Message. |
|
|
|
+| customs_code | String(64) | M | Customs record code |
|
|
|
+| customs_name | String(128) | M | Customs record name |
|
|
|
+| customs_place | String(128) | M | Customs code, see Annex 1 Customs List for details. |
|
|
|
+| allpayOrderNum | String(64) | M | Conversion merchant order number of GoAllPay system. |
|
|
|
+| schemaTransId | String(64) | M | The transaction ID of the payment channel. |
|
|
|
+| merID | String(15) | M | Merchant ID, assigned by GoAllPay. |
|
|
|
+| acqID | String(11) | M | Acquiring Bank ID: "99020344" |
|
|
|
+| paymentSchema | String(10) | M | Channel ID.<br>UnionPay：UP<br>WeChat Pay：WX<br>Alipay：AP |
|
|
|
+| transTime | String(14) | M | Transaction time, format :" yyyyMMddHHmmss" |
|
|
|
+| signType | String(10) | M | "MD5" or "SHA256" |
|
|
|
+| signature | String(32) | M | MD5 or SHA256 signature |
|
|
|
+
|
|
|
+## 4.Annex 1 Customs List
|
|
|
+
|
|
|
+### 4.1 Alipay customs list
|
|
|
+
|
|
|
+| Customs name | Customs code |
|
|
|
+| ---------- | ------------- |
|
|
|
+| General Administration of Customs | ZONGSHU |
|
|
|
+| Hangzhou | HANGZHOU_ZONGSHU |
|
|
|
+| Henan Bonded Logistics Center | ZHENGZHOU |
|
|
|
+| Xinzheng Comprehensive Bonded Zone (Airport) (Push HENAN first, then ZONGSHU) | HENAN |
|
|
|
+| Ningbo | NINGBO |
|
|
|
+| Shanghai | SHANGHAI_CBT |
|
|
|
+| Nansha National Inspection | NANSHAGJ |
|
|
|
+| Tianjin (first push TIANJIN, then ZONGSHU) | TIANJIN |
|
|
|
+| Guangzhou (Airport) (Need to fill in the company's filing information in the Radio And Television Administration) | GUANGZHOU_AIRPORT |
|
|
|
+| Guangzhou (Nansha)（推送广州南沙国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_NANSHA |
|
|
|
+| Guangzhou (Huangpu)（推送广州黄埔国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_HUANGPU |
|
|
|
+| Guangzhou (Shatian)（推送广州沙田国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_SHATIAN |
|
|
|
+
|
|
|
+### 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 | TIANJIN |
|
|
|
+
|
|
|
+### 4.3 UnionPay customs list
|
|
|
+
|
|
|
+| Customs name | Customs code |
|
|
|
+| ----------- | -------- |
|
|
|
+| General Administration of Customs | CUSTOMSHEADOFFICE |
|
|
|
+| Beijing | CUSTOMSHEADOFFICE |
|
|
|
+| Guangzhou | GUANGZHOU |
|
|
|
+| Ningbo | NINGBO |
|
|
|
+| Shanghai | SHANGHAI |
|
|
|
+
|
|
|
+The above list of customs is the customs that supports customs declaration through API in each channel. The actual support situation is subject to the update of each 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 |
|
|
|
+| E1 | Identity information does not match |
|
|
|
+
|
|
|
+***Note: After the UnionPay channel applies for customs declaration, the response code is 04. Processing is in progress. It will take some time to call the declaration query interface to determine the final status.**
|
|
|
+
|
|
|
+## 6.Technical support
|
|
|
+
|
|
|
+If you have problems with debugging, please contact us: support@allpayx.com
|
