API字典 / 海关报关 / 报关API

报关API

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

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

注意：

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

支付单申报规则：

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

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

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

1. 接口说明

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

请求URL: https://apihk.mch.weixin.qq.com/v3/global/customs/orders

请求方式: POST

Path指该参数为路径参数

Query指该参数为URL参数

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

2. 请求参数

参数名	变量	类型[长度限制]	必填	描述
机构APPID	appid	string[1,32]	是	Body 微信分配的公众账号ID 示例值：wxd678efh567hg6787
商户号	mchid	string[1,32]	是	Body 微信支付分配的商户号示例值：1230000109
商户订单号	out_trade_no	string[1,32]	是	Body 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户号下唯一示例值：20150806125346
微信订单号	transaction_id	string[1,32]	是	Body 微信支付返回的订单号示例值：1000320306201511078440737890
海关	customs	string[1,32]	是	Body 海关代码，枚举值参见海关列表示例值：SHANGHAI_ZS
商户海关备案号	merchant_customs_no	string[1,32]	是	Body 商户在海关登记的备案号示例值：123456
关税	duty	int	否	Body 关税，以分为单位，非必填项，不会提交给海关示例值：888
商户子订单号	sub_order_no	string[1,32]	否	Body 商户子订单号，如有拆单则必传注意：仅适用于机构模式示例值：20150806125346
货币类型	fee_type	string[1,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
}

{
    "appid": "wx2421b1c4370ec43b",
    "m",
      "device_id" : "013467007045764",
      "operator_id": "P001",
      "store_info" : {
        "id": "SZTX001"
      }
    }
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. 返回参数

正常返回

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

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

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

返回信息

message

string[1, 256]

是

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

详细的错误描述

detail

object

否

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

参数名	变量	类型[长度限制]	必填	描述
指示错误参数的位置	field	string[1, 256]	是	当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer 当错误参数位于请求的url或者querystring时，填写参数的变量名示例值：#/properties/payer
错误参数的值	value	string[1, 256]	是	错误参数的值示例值：1346177081915535577
具体错误原因	issue	string[1, 256]	是	具体错误原因示例值：与ALLOF schema不符
错误参数的位置	location	string[1, 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"
}

 
{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

4. 错误码

错误码	描述	解决方案
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

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

正常返回

异常返回

返回示例

4. 错误码