# GoAllPay报关接口规范说明文档V5.0.0
>[上海偶可贝网络科技有限公司](https://www.allpayx.com)
>
>- 版本信息：中文 V5.0.0
>- 更新时间：2020 年 6 月

## 1.概述

本文档规定了商户与GoAllPay之间的海关申报产品进行联机交易时使用的报文接口。

## 2.验签说明 

```
1.对于发送到 GoAllPay 系统的请求报文，其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。

2.在 String1 最后直接拼接（不需要用“&”连接）双方约定的签名密钥 Key（接入 GoAllPay 时分配），得到 stringSignTemp 字符串，并对 stringSignTemp 进行加密运算，得到 signature 的值。

3.示例签名串 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说明 

商户服务器和 GoAllPay 网关对接的海关申报相关接口，包括申报、申报查询、申报更新。

### 3.1 通用 API 接入地址 

| 交易名称 | 测试交易地址                               | 生产交易地址                               |
| ------- | ----------------------------------------- | ------------------------------------------ |
| 申报 | https://testapi.allpayx.com/custom/declare | https://api.allpayx.com/custom/declare |
| 申报查询 | https://testapi.allpayx.com/custom/query   | https://api.allpayx.com/custom/query       |
| 申报更新 | https://testapi.allpayx.com/custom/update | https://api.allpayx.com/custom/update |

### 3.2 申报接口

**1.请求报文格式**

| 参数            | 类型        | 属性 | 描述                                                         |
| --------------- | ----------- | ---- | ------------------------------------------------------------ |
| version         | String(12)  | M    | 统一填写为“VER000000005”                                     |
| charSet         | String(6)   | M    | 统一填写为“UTF-8”                                            |
| transType       | String(4)   | M    | 交易类型代码：“DECL”                                         |
| customsDeclarationNo | String(60)  | O    | 报关订单号，商户自行定义。<br>注：支付宝和微信可选送该字段，银联不能送该字段。支付宝和微信如果没有送该字段，会把orderNum作为报关订单号。       |
| orderNum        | String(60)  | M    | 交易ID：商户自行定义，需保证同一商户号下交易ID不能重复       |
| origOrderNum    | String(60)  | M    | 支付成功的订单号                                   |
| productPrice    | String(12)  | M    | 商品金额：如 100 元，表示为 100 或 100.00                    |
| transportPrice  | String(12)  | M    | 运费金额：如 100 元，表示为 100 或 100.00                    |
| tarPrice        | String(12)  | M    | 关税金额：如 100 元，表示为 100 或 100.00                    |
| orderCurrency   | String(3)   | M    | 订单币种：ISO标准。如：人民币填写“CNY”，美元填写"USD"          |
| customs_code    | String(64)  | M    | 商户海关备案编码                                             |
| customs_name    | String(128) | M    | 商户海关备案名称                                             |
| customs_place   | String(128) | M    | 海关，详见附件 1 海关列表                                       |
| name            | String(64)  | M    | 消费者姓名                                                   |
| IDCard          | String(32)  | M    | 消费者身份证号                                               |
| customerAccount | String(64)  | M    | 消费者在商家的注册帐号                                       |
| businessType    | String(2)   | O    | 保税进口：1<br>直邮进口：2<br>如果不填，默认为1保税进口，视申报海关需要填写 |
| merID           | String(15)  | M    | 商户 ID，由GoAllPay 分配                                       |
| acqID           | String(11)  | M    | 收单行 ID "99020344"                                         |
| paymentSchema   | String(10)  | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP                |
| transTime       | String(14)  | M    | 交易时间，格式:"yyyyMMddHHmmss"                               |
| signType        | String(10)  | M    | MD5或SHA256                                                  |
| signature       | String(32)  | M    | 采用 MD5或SHA256 签名                                         |

**2.响应报文格式**

| 参数           | 类型        | 属性 | 描述                                          |
| -------------- | ----------- | ---- | --------------------------------------------- |
| version        | String(12)  | M    | 统一填写为“VER000000005”                      |
| charSet        | String(6)   | M    | 统一填写为“UTF-8”                             |
| transType      | String(4)   | M    | “DECL”                                        |
| orderNum       | String(60)  | M    | 交易ID                                        |
| RespCode       | String(2)   | M    | 应答码 00-成功。详见附件 2 应答码             |
| RespMsg        | String(128) | M    | 应答消息                                      |
| customs_code   | String(64)  | M    | 商户在海关报备的编码                          |
| customs_name   | String(128) | M    | 商户在海关报备的名称                          |
| customs_place  | String(128) | M    | 海关，详见附件 1 海关列表                     |
| allpayOrderNum | String(64)  | M    | GoAllPay系统的转换商户订单号                    |
| schemaTransId  | String(64)  | M    | 支付渠道的交易ID。<br/>注：银联报关需要用该字段作为物流单以及销售单的报关单号 |
| merID          | String(15)  | M    | 商户 ID，由GoAllPay 分配                        |
| acqID          | String(11)  | M    | 收单行 ID "99020344"                          |
| paymentSchema  | String(10)  | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP |
| transTime      | String(14)  | M    | 交易时间，格式："yyyyMMddHHmmss"              |
| signType       | String(10)  | M    | MD5或SHA256                                   |
| signature      | String(32)  | M    | 采用 MD5或SHA256 签名                         |

### 3.3 申报查询接口

**1.请求报文格式**

| 参数          | 类型       | 属性 | 描述                                          |
| ------------- | ---------- | ---- | --------------------------------------------- |
| version       | String(12) | M    | 统一填写为“VER000000005”                      |
| charSet       | String(6)  | M    | 统一填写为“UTF-8”                             |
| transType     | String(4)  | M    | 查询填写“INQY”                                |
| orderNum      | String(60) | M    | 交易ID                                        |
| merID         | String(15) | M    | 商户 ID，由GoAllPay 分配                        |
| acqID         | String(11) | M    | 收单行 ID "99020344"                          |
| paymentSchema | String(10) | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP |
| transTime     | String(14) | M    | 交易时间，格式:"yyyyMMddHHmmss"                |
| signType      | String(10) | M    | MD5或SHA256                                   |
| signature     | String(32) | M    | 采用 MD5或SHA256 签名                        |

**2.响应报文格式**

| 参数           | 类型        | 属性 | 描述                                          |
| ------------- | ----------- | ---- | --------------------------------------------- |
| version        | String(12)  | M    | 统一填写为“VER000000005”                      |
| charSet        | String(6)   | M    | 统一填写为“UTF-8”                             |
| transType      | String(4)   | M    | “DECL”                                        |
| orderNum       | String(60)  | M    | 交易ID                                        |
| RespCode       | String(2)   | M    | 应答码 00-成功。详见附件 2 应答码                                |
| RespMsg        | String(128) | M    | 应答消息                                      |
| customs_code   | String(64)  | M    | 商户在海关报备的编码                          |
| customs_name   | String(128) | M    | 商户在海关报备的名称                          |
| customs_place  | String(128) | M    | 海关，详见附件 1 海关列表                        |
| allpayOrderNum | String(64)  | M    | GoAllPay系统的转换商户订单号                    |
| schemaTransId  | String(64)  | M    | 支付渠道的交易ID。 |
| merID          | String(15)  | M    | 商户 ID，由 GoAllPay 分配                        |
| acqID          | String(11)  | M    | 收单行 ID "99020344"                          |
| paymentSchema  | String(10)  | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP |
| transTime      | String(14)  | M    | 交易时间，格式："yyyyMMddHHmmss"              |
| signType       | String(10)  | M    | MD5或SHA256                                  |
| signature      | String(32)  | M    | 采用 MD5或SHA256 签名                     |

### 3.4 申报更新接口

**1.请求报文格式**

| 参数            | 类型        | 属性 | 描述                                                         |
| --------------- | ----------- | ---- | ------------------------------------------------------------ |
| version         | String(12)  | M    | 统一填写为“VER000000005”                                     |
| charSet         | String(6)   | M    | 统一填写为“UTF-8”                                            |
| transType       | String(4)   | M    | 交易类型代码：“DECL”                                         |
| customsDeclarationNo | String(60)  | O    | 报关订单号，商户自行定义。<br>注：支付宝和微信可选送该字段，银联不能送该字段。支付宝和微信如果没有送该字段，会把orderNum作为报关订单号。       |
| orderNum        | String(60)  | M    | 申报接口中的交易ID   |
| origOrderNum    | String(60)  | M    | 支付成功的订单号 |
| productPrice    | String(12)  | M    | 商品金额：如 100 元，表示为 100 或 100.00                    |
| transportPrice  | String(12)  | M    | 运费金额：如 100 元，表示为 100 或 100.00                    |
| tarPrice        | String(12)  | M    | 关税金额：如 100 元，表示为 100 或 100.00                    |
| orderCurrency   | String(3)   | M    | 订单币种：ISO标准。如：人民币填写“CNY”，美元填写"USD"        |
| customs_code    | String(64)  | M    | 商户海关备案编码                                             |
| customs_name    | String(128) | M    | 商户海关备案名称                                             |
| customs_place   | String(128) | M    | 海关，详见附件 1 海关列表                                    |
| name            | String(64)  | M    | 消费者姓名                                                   |
| IDCard          | String(32)  | M    | 消费者身份证号                                               |
| customerAccount | String(64)  | M    | 消费者在商家的注册帐号                                       |
| businessType    | String(2)   | O    | 保税进口：1，直邮进口：2。如果不填，默认为1保税进口，视申报海关需要填写 |
| merID           | String(15)  | M    | 商户 ID，由GoAllPay 分配                                       |
| acqID           | String(11)  | M    | 收单行 ID "99020344"                                         |
| paymentSchema   | String(10)  | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP |
| transTime       | String(14)  | M    | 交易时间，格式:"yyyyMMddHHmmss"                              |
| signType        | String(10)  | M    | MD5或SHA256                                                  |
| signature       | String(32)  | M    | 采用 MD5或SHA256 签名                                        |

**2.响应报文格式**

| 参数           | 类型        | 属性 | 描述                                          |
| -------------- | ----------- | ---- | --------------------------------------------- |
| version        | String(12)  | M    | 统一填写为“VER000000005”                      |
| charSet        | String(6)   | M    | 统一填写为“UTF-8”                             |
| transType      | String(4)   | M    | “DECL”                                        |
| orderNum       | String(60)  | M    | 交易ID                                        |
| RespCode       | String(2)   | M    | 应答码 00-成功。详见附件 2 应答码             |
| RespMsg        | String(128) | M    | 应答消息                                      |
| customs_code   | String(64)  | M    | 商户在海关报备的编码                          |
| customs_name   | String(128) | M    | 商户在海关报备的名称                          |
| customs_place  | String(128) | M    | 海关，详见附件 1 海关列表                     |
| allpayOrderNum | String(64)  | M    | GoAllPay系统的转换商户订单号                    |
| schemaTransId  | String(64)  | M    | 支付渠道的交易ID                              |
| merID          | String(15)  | M    | 商户 ID，由GoAllPay 分配                        |
| acqID          | String(11)  | M    | 收单行 ID "99020344"                          |
| paymentSchema  | String(10)  | M    | 渠道代码。银联：UP，微信：WX，支付宝：AP |
| transTime      | String(14)  | M    | 交易时间，格式："yyyyMMddHHmmss"              |
| signType       | String(10)  | M    | MD5或SHA256                                   |
| signature      | String(32)  | M    | 采用 MD5或SHA256 签名                         |

## 4.附件 1 海关列表

### 4.1 支付宝海关列表

| 海关名称                                                     | 海关编码               |
| ------------------------------------------------------------ | ---------------------- |
| 总署                                                          | ZONGSHU                |
| 杭州海关                                                     | HANGZHOU_ZONGSHU       |
| 河南保税物流中心                                             | ZHENGZHOU              |
| 新郑综合保税区（空港）（先推送HENAN，再推送ZONGSHU）            | HENAN        |
| 宁波海关                                                     | NINGBO                 |
| 上海海关                                                     | SHANGHAI_CBT           |
| 南沙国检                                                     | NANSHAGJ               |
| 天津海关（先推送TIANJIN，再推送ZONGSHU）                       | TIANJIN     |
| 广州海关（机场）（推送广州机场国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_AIRPORT   |
| 广州海关（南沙）（推送广州南沙国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_NANSHA   |
| 广州海关（黄埔）（推送广州黄埔国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_HUANGPU   |
| 广州海关（沙田）（推送广州沙田国检，备案信息需要传企业在广电的备案信息）| GUANGZHOU_SHATIAN   |

### 4.2 微信海关列表

| 海关名称                                                     | 海关编码        |
| ------------------------------------------------------------ | --------------- |
| 广州（总署版）                                               | GUANGZHOU_ZS    |
| 广州黄埔国检（推送至黄埔国检的订单需分别推送广州（总署版）和广州黄埔国检，即需要请求两次报关接口） | GUANGZHOU_HP_GJ |
| 广州南沙国检（推送至南沙国检的订单需分别推送广州（总署版）和广州南沙国检，即需要请求两次报关接口） | GUANGZHOU_NS_GJ |
| 杭州（总署版）                                               | HANGZHOU_ZS     |
| 宁波                                                         | NINGBO          |
| 郑州（保税物流中心）                                         | ZHENGZHOU_BS    |
| 重庆                                                         | CHONGQING       |
| 上海（总署版）                                               | SHANGHAI_ZS     |
| 深圳                                                         | SHENZHEN        |
| 郑州综保（总署版）                                           | ZHENGZHOU_ZH_ZS |
| 天津                                                         | TIANJIN         |

### 4.3 银联海关列表

| 海关名称       | 海关编码          |
| -------------- | ----------------- |
| 海关总署       | CUSTOMSHEADOFFICE |
| 北京海关       | CUSTOMSHEADOFFICE |
| 广州海关       | GUANGZHOU         |
| 宁波海关       | NINGBO     |
| 上海海关       | SHANGHAI          |

以上海关列表为各渠道支持通过 API 报关的海关，实际支持情况以各渠道更新为准。

## 5.附件 2 应答码

| 应答码 | 描述       |
| ------ | ----------- |
| 00     | 成功         |
| 01     | 失败         |
| 04     | 处理中       |
| 61     | 超过限额     |
| U1     | 商户不存在 |
| U2     | 签名错误     |
| U3     | 报文被篡改   |
| U4     | 缺失参数     |
| U5     | 无效的参数   |
| U6     | 重复的订单号 |
| U7     | 订单不存在   |
| U8     | 参数为空 |
| U9     | 系统错误     |
| P1     | 渠道未配置   |
| P2     | 币种未配置   |
| E1     | 身份信息不匹配   |

***注意：银联渠道申请报关后应答码为04处理中，需要过段时间调用申报查询接口确定最终状态。**

## 6.技术支持

如果您有任何问题，请邮件联系support@allpayx.com