统一下单

更新时间：2025.03.21

除付款码支付场景以外，商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易会话标识后再按Native、JSAPI、APP等不同场景生成交易串调起支付。

接口说明

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

请求URL: https://apihk.mch.weixin.qq.com/pay/unifiedorder

请求方式: POST

是否需要证书: 否

输入参数

参数名	变量名	类型	必填	描述
公众账号ID	appid	String(32)	是	在微信公众平台或开放平台生成的应用ID，全局唯一。请求统一下单接口时请注意APPID的应用属性，例如公众号场景下，需使用应用属性为公众号的APPID。示例值：wx8888888888888888
商户号	mch_id	String(32)	是	微信支付分配的商户号（商户号申请指引）示例值：1230000109
子商户公众账号ID	sub_appid	String(32)	否	微信分配的子商户公众账号ID，如需在支付完成后获取sub_openid则此参数必传。注意：仅适用于机构模式示例值：wx8888888888888888
子商户号	sub_mch_id	String(32)	是	微信支付分配的子商户号注意：仅适用于机构模式示例值：1900000109
设备号	device_info	String(32)	否	终端设备号(门店号或收银设备ID)，注意：PC网页或公众号内支付请传"WEB" 示例值：013467007045764
随机字符串	nonce_str	String(32)	是	随机字符串，不长于32位。推荐随机数生成算法示例值：5K8264ILTKCH16CQ2502SI8ZNMTM67VS
签名	sign	String(64)	是	签名，详见签名生成算法示例值：C380BEC2BFD727A4B6845133519F3AD6
签名类型	sign_type	String(32)	否	签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 示例值：HMAC-SHA256
商品描述	body	String(127)	是	商品或支付单简要描述示例值：Ipad mini 16G 白色
版本 ID	version	String(32)	是	固定值： 1.0 示例：1.0
商品详情	detail	String(6000)	否	商品详细列表，使用Json格式，传输签名前请务必使用CDATA标签将JSON文本串保护起来。 goods_detail └ goods_name String 必填 256 商品名称 └ quantity int 必填 4 商品数量示例值：{"goods_detail":[{"goods_name":"iPhone6s 16G","quantity":1,},{"goods_name":"iPhone6s 32G","quantity":1,}]}
附加数据	attach	String(127)	否	附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据示例值：说明
商户订单号	out_trade_no	String(32)	是	商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*且在同一个商户号下唯一。其他说明见商户订单号示例值：1217752501201407033233368018
标价币种	fee_type	String(16)	是	符合ISO 4217标准的三位字母代码，列表详见货币类型示例值：USD
标价金额	total_fee	int	是	订单总金额，只能为整数，详见标价金额示例值：888
终端IP	spbill_create_ip	String(64)	否	支持IPV4和IPV6两种格式的IP地址。调用微信支付API的机器IP 示例值：8.8.8.8
交易起始时间	time_start	String(14)	否	订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则示例值：20091225091010
交易结束时间	time_expire	String(14)	否	订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。示例值：20091227091010
通知地址	notify_url	String(256)	是	接收微信支付异步通知回调地址示例值：http://www.weixin.qq.com/
交易类型	trade_type	String(16)	是	取值如下：JSAPI，NATIVE，APP，详细说明见参数规定示例值：JSAPI
商品ID	product_id	String(32)	否	trade_type=NATIVE时，此参数必传。此id为二维码中包含的商品ID，商户自行定义。示例值：12235413214070356458058
用户标识	openid	String(128)	否	trade_type=JSAPI，此参数必传，用户在主商户appid下的唯一标识。openid和sub_openid可以选传其中之一，如果选择传sub_openid,则必须传sub_appid。openid如何获取，可参考获取openid 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用户子标识	sub_openid	String(128)	否	trade_type=JSAPI，此参数必传，用户在子商户appid下的唯一标识。openid和sub_openid可以选传其中之一，如果选择传sub_openid,则必须传sub_appid。openid如何获取，可参考获取openid 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
开发票入口开放标识	receipt	String(8)	否	Y，传入Y时，支付成功消息和支付详情页将出现开票入口。需要在微信支付商户平台或微信公众平台开通电子发票功能，传此字段才可生效示例值：Y
场景信息	scene_info	string(256)	否	该字段用于统一下单时上报场景信息，目前支持上报实际门店信息。 { "store_id": "", //门店唯一标识，选填，string(32) "store_name":"”//门店名称，选填，string(64) } 示例值：{ "store_id": "SZT10000", "store_name":"腾讯大厦腾大餐厅" }

举例如下：

1<xml>
2  <appid>wx2421b1c4370ec43b</appid>
3  <body>An apple</body>
4  <device_info>123001</device_info>
5  <fee_type>EUR</fee_type>
6  <mch_id>10000100</mch_id>
7  <nonce_str>f6868b9b16bf4893958afd4a46d73422</nonce_str>
8  <notify_url>https:/localhost/api/apm/notify/wechat</notify_url>
9  <out_trade_no>1678371718207330</out_trade_no>
10  <sign>1B2335BD4A5AC021C8D7EA87E3FF81FF</sign>
11  <sub_mch_id>375907253</sub_mch_id>
12  <total_fee>1</total_fee>
13  <trade_type>NATIVE</trade_type>
14</xml>

注：参数值用XML转义即可，CDATA标签用于说明数据不被XML解析器解析。

返回结果

字段名	变量名	类型	必填	描述
返回状态码	return_code	string(16)	是	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断示例值：SUCCESS
返回信息	return_msg	String(128)	否	返回信息，如非空，为错误原因签名失败参数格式校验错误示例值：签名失败

以下字段在return_code为SUCCESS的时候有返回

字段名	变量名	类型	必填	描述
公众账号ID	appid	String(32)	是	调用接口提交的公众账号ID 示例值：wx8888888888888888
商户号	mch_id	String(32)	是	调用接口提交的商户号示例值：1900000109
子商户公众账号ID	sub_appid	String(32)	否	微信分配的子商户公众账号ID 注意：仅适用于机构模式示例值：wx8888888888888888
子商户号	sub_mch_id	String(32)	是	微信支付分配的子商户号注意：仅适用于机构模式示例值：1900000109
设备号	device_info	String(32)	否	调用接口提交的终端设备号。示例值：013467007045764
随机字符串	nonce_str	String(32)	是	微信返回的随机字符串示例值：5K8264ILTKCH16CQ2502SI8ZNMTM67VS
签名	sign	String(64)	是	微信返回的签名，详见签名算法示例值：C380BEC2BFD727A4B6845133519F3AD6
业务结果	result_code	String(16)	是	SUCCESS/FAIL 示例值：SUCCESS
错误代码	err_code	String(32)	否	详细参见第6节错误列表示例值：SYSTEMERROR
错误代码描述	err_code_des	String(128)	否	错误返回的信息描述示例值：系统错误

以下字段在return_code 和result_code都为SUCCESS的时候有返回

字段名	变量名	类型	必填	描述
交易类型	trade_type	string(16)	是	调用接口提交的交易类型，取值如下：JSAPI，NATIVE，APP，详细说明见参数规定示例值：JSAPI
预支付交易会话标识	prepay_id	String(64)	是	微信生成的预支付会话标识，用于后续接口调用中使用，该值有效期为2小时示例值：wx201410272009395522657a690389285100
二维码链接	code_url	String(64)	否	trade_type=NATIVE时有返回，此url用于生成支付二维码，然后提供给用户进行扫码支付。注意：code_url的值并非固定，使用时按照URL格式转成二维码即可示例值：weixin://wxpay/bizpayurl/up?pr=NwY5Mz9&groupid=00

举例如下：

1<xml>
2   <return_code><![CDATA[SUCCESS]]></return_code>
3   <return_msg><![CDATA[OK]]></return_msg>
4   <result_code><![CDATA[SUCCESS]]></result_code>
5   <mch_id><![CDATA[10000100]]></mch_id>
6   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
7   <sub_mch_id><![CDATA[375907253]]></sub_mch_id>
8   <device_info><![CDATA[123001]]></device_info>
9   <nonce_str><![CDATA[oau45q3ZBIghSWMq]]></nonce_str>
10   <sign><![CDATA[A097F9242DF04CD4467D814987538248]]></sign>
11   <prepay_id><![CDATA[wx032345531721563d76748ad2f15b480000]]></prepay_id>
12   <trade_type><![CDATA[NATIVE]]></trade_type>
13   <code_url><![CDATA[weixin://wxpay/bizpayurl?pr=IjIU6hZzz]]></code_url>
14</xml>

错误码

名称	描述	原因	解决方案
INVALID_REQUEST	参数错误	参数格式有误或者未按规则上传	订单重入时，要求参数值与原请求一致，请确认参数问题
NOAUTH	商户无此接口权限	商户未开通此接口权限	请商户前往申请此接口权限
NOTENOUGH	余额不足	用户账号余额不足	用户账号余额不足，请用户充值或更换支付卡后再支付
ORDERPAID	商户订单已支付	商户订单已支付，无需重复操作	商户订单已支付，无需更多操作
ORDERCLOSED	订单已关闭	当前订单已关闭，无法支付	当前订单已关闭，请重新下单
SYSTEMERROR	系统错误	系统超时	系统异常，请用相同参数重新调用
APPID_NOT_EXIST	APPID不存在	参数中缺少APPID	请检查APPID是否正确
MCHID_NOT_EXIST	MCHID不存在	参数中缺少MCHID	请检查MCHID是否正确
APPID_MCHID_NOT_MATCH	appid和mch_id不匹配	appid和mch_id不匹配	请确认appid和mch_id是否匹配
LACK_PARAMS	缺少参数	缺少必要的请求参数	请检查参数是否齐全
OUT_TRADE_NO_USED	商户订单号重复	同一笔交易不能多次提交	请核实商户订单号是否重复提交
SIGNERROR	签名错误	参数签名结果不正确	请检查签名参数和方法是否都符合签名算法要求
XML_FORMAT_ERROR	XML格式错误	XML格式错误	请检查XML参数格式是否正确
REQUIRE_POST_METHOD	请使用post方法	未使用post传递参数	请检查请求参数是否通过post方法提交
POST_DATA_EMPTY	post数据为空	post数据不能为空	请检查post数据是否为空
NOT_UTF8	编码格式错误	未使用指定编码格式	请使用UTF-8编码格式