AllPay_Customs_Integration_Specification_CH.md 19 KB

GoAllPay报关接口规范说明文档V5.0.0

上海偶可贝网络科技有限公司

  • 版本信息:中文 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. 签名过程示例:

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) 报关订单号,商户自行定义。
注:支付宝和微信可选送该字段,银联不能送该字段。支付宝和微信如果没有送该字段,会把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
直邮进口: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 签名
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) 报关订单号,商户自行定义。
注:支付宝和微信可选送该字段,银联不能送该字段。支付宝和微信如果没有送该字段,会把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