统一下单API(支持单品优惠)
应用场景
统一下单API接入流程、方式和协议与原统一下单文档一致,本节单独针对接入单品优惠字段作详细介绍。
享受了单品优惠的订单将不能使用原退款接口进行部分退款,只能整单退款,或者通过单品优惠退款接口进行部分退款。详细内容请见“注意事项”。
接口地址
URL地址:https://api.mch.weixin.qq.com/pay/unifiedorder
URL地址:https://api2.mch.weixin.qq.com/pay/unifiedorder(备用域名)见跨城冗灾方案
是否需要证书
不需要。
输入参数
名称 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
接口版本号 | version | 否 | String(32) | 1.0 | 新增字段,接口版本号,区分原接口,默认填写1.0。 单品优惠:必填,上传version字段,返回参数会有差异,详情参考:《注意事项》 |
商品标记 | goods_tag | 否 | String(32) | 订单优惠标记,用于区分订单是否可以享受优惠,字段内容在微信后台配置券时进行设置,说明详见代金券或立减优惠 | |
商品详情 | detail | 是 | String(6000) | 示例见下文 | 新增字段,单品优惠活动该字段必传,且必须按照规范上传,JSON格式,详见下文【单品优惠活动字段说明】 |
其他字段列表见 |
单品优惠活动detail字段列表说明:
名称 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
订单原价 | cost_price | 否 | int | 608800 | 1.商户侧一张小票订单可能被分多次支付,订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等,则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付,以享受多次优惠的情况,正常支付订单不必上传此参数。 |
商品小票ID | receipt_id | 否 | String(32) | wx123 | 商家小票ID |
单品列表 | goods_detail | 是 | String | 示例见下文 | 单品信息,使用Json数组格式提交 |
单品优惠活动goods_detail字段说明:
名称 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商品编码 | goods_id | 是 | String(32) | 1246464644 | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 |
微信支付商品编码 | wxpay_goods_id | 否 | String(32) | 1001 | 微信支付定义的统一商品编号(没有可不传) |
商品名称 | goods_name | 否 | String(256) | iPhone6s 16G | 商品的实际名称 |
商品数量 | quantity | 是 | int | 1 | 用户购买的数量 |
商品单价 | price | 是 | int | 528800 | 单位为:分。如果商户有优惠,需传输商户优惠后的单价(例如:用户对一笔100元的订单使用了商场发的纸质优惠券100-50,则活动商品的单价应为原单价-50) |
detail字段值举例如下:
{
"cost_price": 608800,
"receipt_id": "wx123",
"goods_detail": [ //注意goods_detail字段的格式为"goods_detail":[{}],较多商户写成"goods_detail":{}
{
"goods_id": "1246464644",
"wxpay_goods_id": "1001",
"goods_name": "",
"quantity": 1,
"price": 528800
},
{
"goods_id": "1246464644",
"wxpay_goods_id": "1002",
"goods_name": "iPhone6s 32G",
"quantity": 1,
"price": 608800
}
]
}
提交支付数据举例:
<xml>
<appid>wxdace645e0bc2c424</appid>
<attach>test</attach>
<auth_code>130050378319653252</auth_code>
<body>下单测试</body>
<detail><![CDATA[{"cost_price":1,"receipt_id":"wx123","goods_detail":[{"goods_id":"1246464644","wxpay_goods_id":"1001","goods_name":"iPhone6s 16G","quantity":1,"price":1},{"goods_id":"1246464644","wxpay_goods_id":"1002","goods_name":"iPhone6s 32G","quantity":1,"price":1}]}]]></detail>
<device_info>TEST01</device_info>
<goods_tag>MEETING</goods_tag>
<mch_id>1900009001</mch_id>
<nonce_str>4b4f6f692547affd2c8fadb39fed603a</nonce_str>
<out_trade_no>19000090011489146530</out_trade_no>
<spbill_create_ip>14.23.150.211</spbill_create_ip>
<sub_mch_id>11383918</sub_mch_id>
<total_fee>503</total_fee>
<version>1.0</version>
<sign>144FF79B7391FE1BD0708470B7D8A2E3</sign>
<trade_type>JSAPI</trade_type>
</xml>
注:参数值用XML转义即可,CDATA标签用于说明数据不被XML解析器解析。
返回结果
下单接口返回保持不变:
名称 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
其他字段列表见 |