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

## 1. 概述

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

## 2. 签名规则

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


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


3. 签名过程示例：

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 说明 

统一支持POST和GET请求，支持form和JSON格式提交参数。

### 3.1 API 列表 

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

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

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

### 3.3 申报查询接口

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

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

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

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

### 3.4 申报更新接口

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

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

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

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

## 4. 附件 1 海关列表

### 4.1 支付宝海关列表

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

### 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 |
| 上海海关       | SHANGHAI          |
| 宁波海关       | NINGBO     |
| 杭州海关总署版 | HANGZHOU |
| 重庆海关       | CHONGQING |
| 河南电子口岸       | HENAN |
| 深圳海关       | SHENZHEN |
| 福州海关       | FUZHOU |
| 厦门海关       | XIAMEN |
| 成都海关       | CHENGDU |
| 青岛海关       | QINGDAO |
| 大连综试区     | DALIAN |

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

## 5. 附件 2 应答码

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

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

## 6. 技术支持

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