统一下单

POST

/pay/unifiedorder

应用场景

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

状态机

支付状态转变如下：

错误码

名称	描述	原因	解决方案
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编码格式

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST '/pay/unifiedorder' \
--header 'Content-Type: application/xml' \
--data-raw '<xml>
   <appid>wx2421b1c4370ec43b</appid>
   <attach>支付测试</attach>
   <body>JSAPI支付测试</body>
   <mch_id>10000100</mch_id>
   <detail><![CDATA[{ "goods_detail":[ { "goods_id":"iphone6s_16G", "wxpay_goods_id":"1001", "goods_name":"iPhone6s 16G", "quantity":1, "price":528800, "goods_category":"123456", "body":"苹果手机" }, { "goods_id":"iphone6s_32G", "wxpay_goods_id":"1002", "goods_name":"iPhone6s 32G", "quantity":1, "price":608800, "goods_category":"123789", "body":"苹果手机" } ] }]]></detail>
   <nonce_str>1add1a30ac87aa2db72f57a2375d8fec</nonce_str>
   <notify_url>https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url>
   <openid>oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</openid>
   <out_trade_no>1415659990</out_trade_no>
   <spbill_create_ip>14.23.150.211</spbill_create_ip>
   <total_fee>1</total_fee>
   <trade_type>JSAPI</trade_type>
   <sign>0CB01533B8C1EF103065174F50BCA001</sign>
</xml>'

响应示例

200 - 成功 - 成功示例

<xml>
   <return_code><![CDATA[SUCCESS]]></return_code>
   <return_msg><![CDATA[OK]]></return_msg>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <mch_id><![CDATA[10000100]]></mch_id>
   <nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
   <openid><![CDATA[oUpF8uMuAJO_M2pxb1Q9zNjWeS6o]]></openid>
   <sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
   <result_code><![CDATA[SUCCESS]]></result_code>
   <prepay_id><![CDATA[wx201411101639507cbf6ffd8b0779950874]]></prepay_id>
   <trade_type><![CDATA[JSAPI]]></trade_type>
</xml>

请求参数

Body 参数application/xml

appid

string

公众账号ID

必需

微信支付分配的公众账号ID（企业号corpid即为此appid）

attach

string

附加数据

可选

附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用。

body

string

商品描述

必需

商品简单描述，该字段请按照规范传递，具体请见参数规定

mch_id

string

商户号

必需

微信支付分配的商户号

detail

string

商品详情

可选

商品详细描述，对于使用单品优惠的商户，该字段必须按照规范上传，详见“单品优惠参数说明”

nonce_str

string

随机字符串

必需

随机字符串，长度要求在32位以内。推荐随机数生成算法

notify_url

string

通知地址

必需

body 异步接收微信支付结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。公网域名必须为https，如果是走专线接入，使用专线NAT IP或者私有回调域名可使用http

openid

string

用户标识

可选

trade_type=JSAPI时（即JSAPI支付），此参数必传，此参数为微信用户在商户对应appid下的唯一标识。openid如何获取，可参考【获取openid】。企业号请使用【企业号OAuth2.0接口】获取企业号内成员userid，再调用【企业号userid转openid接口】进行转换

out_trade_no

string

商户订单号

必需

商户系统内部订单号，要求32个字符内（最少6个字符），只能是数字、大小写字母_-|*且在同一个商户号下唯一。详见商户订单号

spbill_create_ip

string

终端IP

必需

支持IPV4和IPV6两种格式的IP地址。用户的客户端IP

total_fee

string

标价金额

必需

订单总金额，单位为分，详见支付金额

trade_type

string

交易类型

必需

JSAPI -JSAPI支付 NATIVE -Native支付 APP -APP支付说明详见参数规定

sign

string

签名

必需

通过签名算法计算得出的签名值，详见签名生成算法

sign_type

string

签名类型

可选

签名类型，默认为MD5，支持HMAC-SHA256和MD5。

device_info

string

设备号

可选

自定义参数，可以为终端设备号(门店号或收银设备ID)，PC网页或公众号内支付可以传"WEB"

fee_type

string

标价币种

可选

符合ISO 4217标准的三位字母代码，默认人民币：CNY，详细列表请参见货币类型

time_start

string

交易起始时间

可选

订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则

time_expire

string

交易结束时间

可选

订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。

goods_tag

string

订单优惠标记

可选

订单优惠标记，使用代金券或立减优惠功能时需要的参数，说明详见代金券或立减优惠

product_id

string

商品ID

可选

trade_type=NATIVE时，此参数必传。此参数为二维码中包含的商品ID，商户自行定义。

limit_pay

string

指定支付方式

可选

上传此参数no_credit--可限制用户不能使用信用卡支付

receipt

string

电子发票入口开放标识

可选

Y，传入Y时，支付成功消息和支付详情页将出现开票入口。需要在微信支付商户平台或微信公众平台开通电子发票功能，传此字段才可生效

profit_sharing

string

是否需要分账

可选

Y-是，需要分账 N-否，不分账字母要求大写，不传默认不分账

scene_info

array [object {4}]

场景信息

可选

该字段常用于线下活动时的场景信息上报，支持上报实际门店信息，商户也可以按需求自己上报相关信息。该字段为JSON对象数据，对象格式为{"store_info":{"id": "门店ID","name": "名称","area_code": "编码","address": "地址" }} ，字段详细说明请点击行前的+展开

string

门店id

必需

门店编号，由商户自定义

name

string

门店名称

可选

门店名称，由商户自定义

area_code

string

门店行政区划码

可选

门店所在地行政区划码，详细见《最新县及县以上行政区划代码》

address

string

门店详细地址

可选

门店详细地址，由商户自定义

示例

返回响应

🟢200成功

application/json

Body

return_code

string

返回状态码

必需

SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断

return_msg

string

返回信息

必需

当return_code为FAIL时返回信息为错误原因，例如签名失败参数格式校验错误

appid

string

公众账号ID

必需

调用接口提交的公众账号ID

mch_id

string

商户号

必需

调用接口提交的商户号

nonce_str

string

随机字符串

必需

微信返回的随机字符串

openid

string

必需

sign

string

签名

必需

微信返回的签名值，详见签名算法

result_code

string

业务结果

必需

SUCCESS/FAIL

prepay_id

string

预支付交易会话标识

必需

微信生成的预支付会话标识，用于后续接口调用中使用，该值有效期为2小时。此字段在return_code 和result_code都为SUCCESS的时候有返回

trade_type

string

交易类型

必需

JSAPI -JSAPI支付 NATIVE -Native支付 APP -APP支付说明详见参数规定
此字段在return_code 和result_code都为SUCCESS的时候有返回

code_url

string

二维码链接

可选

trade_type=NATIVE时有返回，此url用于生成支付二维码，然后提供给用户进行扫码支付。注意：code_url的值并非固定，使用时按照URL格式转成二维码即可。时效性为2小时。此字段在return_code 和result_code都为SUCCESS的时候有返回

device_info

string

设备号

可选

自定义参数，可以为请求支付的终端设备号等

err_code

string

错误代码

可选

当result_code为FAIL时返回错误代码，详细参见下文错误列表

err_code_des

string

错误代码描述

可选

当result_code为FAIL时返回错误描述，详细参见下文错误列表

🟢200失败

修改于 2022-07-22 12:09:48

支付常见问题

查询订单

统一下单

应用场景#

状态机#

错误码#

请求参数

返回响应

应用场景

状态机

错误码