微信支付境外文档-报关

返回上一层报关 / 报关API

报关API

最新更新时间：2020.04.03 版本说明

该接口用于商户提交海关需要的订单附加信息。

注意：

以下为财付通的海关备案信息，一般海关会提供，如果没有请参考下表：财付通海关备案名称：财付通支付科技有限公司财付通10位海关注册编码：4403169D3W.。

支付单申报规则：

a.如果没有拆单，就以支付时的商户订单号out_trade_no、微信支付订单号transaction_id、原支付单对应的人民币金额（如有部分退款，减去部分退款金额）申报。

b.如果拆单了，就以申报接口传的商户子单号sub_order_no和接口返回的子支付单号sub_order_id、申报接口传的order_fee金额申报。

c.拆单的判断标准：调用支付申报接口时，商户传了商户子单号sub_order_no就认为是拆单。

接口说明

适用对象：直连模式机构模式

接口URL：https://apihk.mch.weixin.qq.com/global/v3/customs/orders

请求方式：POST

接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3/

path 指该参数为路径参数

query 指该参数为URL参数

body 指该参数需在请求JSON传参

请求参数

参数名	变量	类型	必填	描述
机构APPID	appid	string(32)	是	body 微信分配的公众账号ID 示例值：wxd678efh567hg6787
商户号	mchid	string(32)	是	body 微信支付分配的商户号示例值：1230000109
商户订单号	out_trade_no	string(32)	是	body 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户号下唯一示例值：20150806125346
微信订单号	transaction_id	string(32)	是	body 微信支付返回的订单号示例值：1000320306201511078440737890
海关	customs	string(32)	是	body 海关代码，枚举值参见参数规定-海关列表示例值：SHANGHAI_ZS
商户海关备案号	merchant_customs_no	string(32)	是	body 商户在海关登记的备案号示例值：123456
关税	duty	int	否	body 关税，以分为单位，非必填项，不会提交给海关示例值：888
商户子订单号	sub_order_no	string(32)	否	body 商户子订单号，如有拆单则必传注意：仅适用于机构模式示例值：20150806125346
货币类型	fee_type	string(32)	否	body 微信支付订单支付时使用的币种，暂只支持人民币CNY，如有拆单则必传示例值：CNY
子订单金额	order_fee	int	否	body 子订单金额，以分为单位，不能超过原订单金额，order_fee=transport_fee+product_fee（应付金额=物流费+商品价格），如有拆单则必传示例值：888
物流费用	transport_fee	int	否	body 物流费用，以分为单位，如有拆单则必传示例值：888
商品费用	product_fee	int	否	body 商品费用，以分为单位，如有拆单则必传示例值：888

请求示例：

JSON

{
  "appid": "wxd678efh567hg6787",
  "mchid": "1230000109",
  "out_trade_no": "20150806125346",
  "transaction_id": "1000320306201511078440737890",
  "customs": "SHANGHAI_ZS",
  "merchant_customs_no": "123456",
  "duty": 888,
  "sub_order_no": "20150806125346",
  "fee_type": "CNY",
  "order_fee": 888,
  "transport_fee": 888,
  "product_fee": 888
}

    
｛
JAVA示例代码
｝

返回参数

正常返回

参数名	变量	类型	必填	描述
机构APPID	appid	string(32)	是	微信分配的公众账号ID 示例值：wxd678efh567hg6787
商户号	mchid	string(32)	是	微信支付分配的商户号示例值：1230000109
报关状态	state	string(32)	是	申报结果状态码 PROCESSING：申报中 UNDECLARED：未申报 SUBMITTED：已修改未申报 SUCCESS：申报成功 FAIL：申报失败 EXCEPT：海关接口异常示例值：PROCESSING
商户订单号	out_trade_no	string(32)	是	商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户号下唯一示例值：20150806125346
微信订单号	transaction_id	string(32)	是	微信支付返回的订单号示例值：1000320306201511078440737890
商户子订单号	sub_order_no	string(32)	否	商户子订单号，如有拆单则返回注意：仅适用于机构模式示例值：20150806125346
微信子订单号	sub_order_id	string(32)	否	微信子订单号，如有拆单则返回注意：仅适用于机构模式示例值：20150806125346
核验机构	verify_department	string(16)	是	核验机构代码 UNIONPAY：银联 NETSUNION：网联 OTHERS：其他注：商户需将该字段取值UNIONPAY, NETSUNION, OTHERS映射至海关verDept字段的1、2、3 示例值：UNIONPAY
核验机构交易流水号	Verify_department_trade_id	string(64)	是	交易流水号，来自验核机构，如银联记录的交易流水号，供商户报备海关示例值：2018112288340107038204310100000

异常返回

参数名

变量

类型

必填

描述

返回状态码

code

string（32）

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string（256）

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

+详细错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下文

参数名	变量	类型	必填	描述
指示错误参数的字段	field	string(256)	是	当错误参数位于请求 body 的 JSON 时填写指向参数的 JSON Pointer; 当错误参数位于请求的 url 或者 querystring 时，填写参数的变量名示例值：#/properties/payer
错误参数的值	value	string(256)	是	错误参数的值示例值：1346177081915535577
具体错误原因	issue	string(256)	是	具体错误原因示例值：与 ALLOF schema 不符
错误参数的位置	location	string(256)	否	body:错误参数位于请求 body 的 JSON 中 url:错误参数位于请求 url 中 query:错误参数位于请求的 querystring 中示例值：body

返回示例：

正常示例

{
  "appid": "wxd678efh567hg6787",
  "mchid": "1230000109",
  "state": "PROCESSING",
  "out_trade_no": "20150806125346",
  "transaction_id": "1000320306201511078440737890",
  "sub_order_no": "20150806125346",
  "sub_order_id": "20150806125346",
  "verify_department": "UNIONPAY",
  "verify_department_trade_id": "2018112288340107038204310100000"
}

错误码

错误码	描述	解决方案
INVALID_REQUEST	商户海关申报重入信息不一致	若需要修改支付单信息，请使用报关修改接口；若需要重新推送支付单，请使用信息重推接口
	海关配置未设置	报关接口需要商户已配置过海关信息才可以访问。请参照上文中的海关备案指引，进行海关信息报备
	订单金额不匹配	报关的订单金额必须和支付的金额一致，请检查报关订单的金额是否正确
	已退款订单不允许申报	订单已退款，不允许申报
NOAUTH	商户未在当前申报的海关进行备案	商户未在申报的海关中备案，请商户完成备案后重试；
NOAUTH	未开通自助清关功能	请检查当前商户是否已开通自助清关功能，开通路径：微信支付商户平台-产品中心-自助清关中申请开通。
PARAM_ERROR	商户号(mch_id)未设置	商户号为必传参数，请求时必传。请检查商户号是否为空
	无效的商户号长度	请检查商户号长度是否为10位
	币种类型未设置	拆单情况下，币种为必填参数。请检查fee_type是否为空。
	商户订单号(out_trade_no)未设置	请检查商户订单号(out_trade_no）是否为空
	微信订单号(transaction_id)未设置	请检查微信订单号(transaction_id)是否为空
	无效的微信订单号长度	微信订单号为28位数字，请确保长度一致，请检查微信订单号(transaction_id)是否正确
	海关信息未设置	海关信息为必传字段，请检查海关信息是否为空
	海关备案号未设置	请检查备案号是否为空
	无效的海关备案号长度	海关备案号一般为6位字符串，请检查海关备案号是否正确
	无效的子订单号长度(sub_order_no)	子订单号要求是32位以内的字符串，请检查子订单号长度是否正确
	AppId未设置	请检查appid是否正确
	交易币种与商户结算币种不一致	请检查所传币种参数（fee_type）是否为空
	参数错误	参数错误，可能参数有误或参数遗漏，请检查接口参数是否按要求提交
	订单金额信息有误	订单金额与支付单金额不符，请检查后重新申报
	交易单信息有误	交易单信息有误，请检查后重新申报
	商户拆单申报金额不正确	商户折单金额大于原支付单金额，请检查后重新申报
	交易币种与商户结算币种不一致	请重新报关，或联系微信支付小助手排查原因
	拆单申报时参数缺漏	拆单时fee_type、order_fee、transport_fee和product_fee必传
SYSTEMERROR	系统错误	请重新报关，或联系微信支付小助手排查原因

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

报关 API

报关API

注意：

接口说明

请求参数

请求示例：

返回参数

正常返回

异常返回

返回示例：

错误码

版本说明