---
url: "https://pay.weixin.qq.com/doc/v3/partner/4012738604.md"
title: "H5下单"
doc_id: 4012738604
---

>更新时间：2025.03.31

用户在服务商或子商户（也叫特约商户）H5页面选择微信支付后，商户需调用该接口在微信支付下单，生成用于[调起支付](https://pay.weixin.qq.com/doc/v3/partner/4012085683.md)的H5支付链接（h5\_url）。




## 接口说明

支持商户：【普通服务商】

请求方式：【POST】 `/v3/pay/partner/transactions/h5`

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/partner/4012082567.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考 [签名认证](https://pay.weixin.qq.com/doc/v3/partner/4012365870.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `application/json` |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| sp_appid | string(32) | true | 【服务商APPID】是服务商在微信[开放平台](https://open.weixin.qq.com/)（移动应用）或[公众平台](https://mp.weixin.qq.com/)（公众号/小程序）上申请的一个唯一标识。此处，可以填写这三种类型中的任意一种APPID，并确保该sp\_appid与sp\_mchid有绑定关系。具体请参考[服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md)。 |
| sp_mchid | string(32) | true | 【服务商商户号】是由微信支付系统生成并分配给每个服务商的唯一标识符，具体请参考[服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md)。 |
| sub_appid | string(32) | false | 【子商户APPID】是子商户在微信[开放平台](https://open.weixin.qq.com/)（移动应用）或[公众平台](https://mp.weixin.qq.com/)（公众号/小程序）上申请的一个唯一标识。此处，可以填写这三种类型中的任意一种APPID，并确保该sub\_appid与sub\_mchid有绑定关系。具体请参考[服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md)。 |
| sub_mchid | string(32) | true | 【子商户号】由服务商为子商户进件后获取，具体请参考[服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md)。 |
| description | string(127) | true | 【商品描述】商品信息描述，用户微信账单的商品字段中可见(可参考[H5支付示例说明](https://pay.weixin.qq.com/doc/v3/partner/4012074916.md#2%E3%80%81H5%E6%94%AF%E4%BB%98%E6%A8%A1%E5%BC%8F%E4%BB%8B%E7%BB%8D)-账单示意图)，服务商需传递能真实代表商品信息的描述，不能超过127个字符。 |
| out_trade_no | string(32) | true | 【商户订单号】服务商系统内部订单号，要求6-32个字符内，只能是数字、大小写字母\_-&#124;\* 且在同一个服务商商户号下唯一。 |
| time_expire | string(64) | false | 【支付结束时间】<br>1、定义：支付结束时间是指用户能够完成该笔订单支付的最后时限，并非订单关闭的时间。超过此时间后，用户将无法对该笔订单进行支付。如商户需在超时后关闭订单，请调用[关闭订单API](https://pay.weixin.qq.com/doc/v3/partner/4012759669.md)接口。<br>2、格式要求：支付结束时间需遵循[rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)标准格式： `yyyy-MM-DDTHH:mm:ss+TIMEZONE`。 `yyyy-MM-DD` 表示年月日； `T` 字符用于分隔日期和时间部分； `HH:mm:ss` 表示具体的时分秒； `TIMEZONE` 表示时区（例如， `+08:00` 对应东八区时间，即北京时间）。<br>示例： `2015-05-20T13:29:35+08:00` 表示北京时间2015年5月20日13点29分35秒。<br>3、若未指定支付结束时间，系统默认以下单时间为起始点计算时效；超过 7 天未支付的订单，无法再支付。<br>4、注意事项：<br><ul><li>若当前实际时间已超过订单设置的支付结束时间（time\_expire），建议先使用关单接口关闭订单，再使用新的商户订单号重新下单，生成全新订单供用户支付。</li><li>支付结束时间不能早于下单时间后1分钟，若设置的支付结束时间早于该时间，系统将自动调整为下单时间后1分钟作为支付结束时间。</li><li>传递的支付结束时间需在下单时间的15天以内，如超过15天，微信支付会自动将该时间调整为下单时间后的第15天。</li></ul> |
| attach | string(128) | false | 【商户数据包】服务商在创建订单时可传入自定义数据包，该数据对用户不可见，用于存储订单相关的服务商自定义信息，其总长度限制在128字符以内。支付成功后[查询订单API](https://pay.weixin.qq.com/doc/v3/partner/4012759661.md)和[支付成功回调通知](https://pay.weixin.qq.com/doc/v3/partner/4012085680.md)均会将此字段返回给服务商，并且该字段还会体现在交易账单。 |
| notify_url | string(255) | true | 【商户回调地址】服务商接收 [支付成功回调通知](https://pay.weixin.qq.com/doc/v3/partner/4012085680.md) 的地址，需按照 [notify\_url填写注意事项](https://pay.weixin.qq.com/doc/v3/partner/4012082570.md) 规范填写。 |
| goods_tag | string(32) | false | 【订单优惠标记】[代金券](https://pay.weixin.qq.com/doc/v3/partner/4012087800.md)在创建时可以配置多个订单优惠标记，标记的内容由创券商户自定义设置。详细参考：[创建代金券批次API](https://pay.weixin.qq.com/doc/v3/partner/4012534537.md)。<br>如果代金券有配置订单优惠标记，则必须在该参数传任意一个配置的订单优惠标记才能使用券。<br>如果代金券没有配置订单优惠标记，则可以不传该参数。<br>示例：<br>如有两个活动，活动A设置了两个优惠标记：WXG1、WXG2；活动B设置了两个优惠标记：WXG1、WXG3；<br>下单时优惠标记传WXG2，则订单参与活动A的优惠；<br>下单时优惠标记传WXG3，则订单参与活动B的优惠；<br>下单时优惠标记传共同的WXG1，则订单参与活动A、B两个活动的优惠； |
| settle_info | object | false | 【结算信息】 结算信息 |
| settle_info.profit_sharing | boolean | false | 【分账标识】订单的分账标识在下单时设置，传入 `true` 表示在订单支付成功后可进行分账操作。以下是详细说明：<br><ul><li>需要分账（传入 `true`）：<br>订单收款成功后，资金将被冻结并转入子商户基本账户的不可用余额。服务商可通过[请求分账API](https://pay.weixin.qq.com/doc/v3/partner/4012690683.md)，将收款资金分配给服务商或其他商户及用户。完成分账操作后，可通过接口 [解冻剩余资金](https://pay.weixin.qq.com/doc/v3/partner/4012466860.md)，或在支付成功30天后自动解冻。</li><li>不需要分账（传入 `false` 或不传，默认为 `false`）：<br>订单收款成功后，资金不会被冻结，而是直接转入子商户基本账户的可用余额。</li></ul> |
| support_fapiao | boolean | false | 【电子发票入口开放标识】 传入true时，支付成功消息和支付详情页将出现开票入口。需要在微信支付服务商平台或微信公众平台开通电子发票功能，传此字段才可生效。 详细参考：[电子发票介绍](https://pay.weixin.qq.com/doc/v3/partner/4015792553.md)<br>true：是<br>false：否 |
| amount | object | true | 【订单金额】订单金额信息 |
| amount.total | integer | true | 【总金额】 订单总金额，单位为分，整型，必须大于0。<br>示例：1元应填写 100 |
| amount.currency | string(16) | false | 【货币类型】符合ISO 4217标准的三位字母代码，固定传：CNY，代表人民币。 |
| detail | object | false | 【商品详情】 商品详情描述，该结构去除多余空格换行压缩后，总长度不能超过6144字节。 |
| detail.cost_price | integer | false | 【订单原价】<br>1、商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。<br>2、当订单原价与支付金额不相等，则不享受优惠。<br>3、该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。 |
| detail.invoice_id | string(32) | false | 【商品小票ID】 商家小票ID |
| detail.goods_detail | array[object] | false | 【单品列表】订单商品明细列表，至少传入1条 |
| detail.goods_detail.merchant_goods_id | string(32) | true | 【商户侧商品编码】 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。 |
| detail.goods_detail.wechatpay_goods_id | string(32) | false | 【微信支付商品编码】 微信支付定义的统一商品编码（没有可不传） |
| detail.goods_detail.goods_name | string(256) | false | 【商品名称】 商品的实际名称 |
| detail.goods_detail.quantity | integer | true | 【商品数量】 用户购买的数量 |
| detail.goods_detail.unit_price | integer | true | 【商品单价】整型，单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的纸质优惠券100-50，则活动商品的单价应为原单价-50) |
| scene_info | object | true | 【场景信息】 场景信息 |
| scene_info.payer_client_ip | string(45) | true | 【用户终端IP】 用户的客户端IP，支持IPv4和IPv6两种格式的IP地址。获取方式详见 [获取用户ip指引](https://pay.weixin.qq.com/doc/v3/partner/4018675960.md) |
| scene_info.device_id | string(32) | false | 【商户端设备号】 商户端设备号（门店号或收银设备ID）。 |
| scene_info.store_info | object | false | 【商户门店信息】 商户门店信息 |
| scene_info.store_info.id | string(32) | true | 【门店编号】商户侧门店编号，总长度不超过32字符，由商户自定义。 |
| scene_info.store_info.name | string(256) | false | 【门店名称】 商户侧门店名称，由商户自定义。 |
| scene_info.store_info.area_code | string(32) | false | 【地区编码】 地区编码，详细请见 [省市区编号对照表](https://pay.weixin.qq.com/doc/v3/partner/4012082815.md)。 |
| scene_info.store_info.address | string(512) | false | 【详细地址】 详细的商户门店地址，由商户自定义。 |
| scene_info.h5_info | object | true | 【H5场景信息】 |
| scene_info.h5_info.type | string(32) | true | 【场景类型】 场景类型，使用H5支付的场景：Wap、iOS、Android |
| scene_info.h5_info.app_name | string(64) | false | 【应用名称】 应用名称 |
| scene_info.h5_info.app_url | string(128) | false | 【网站URL】 网站URL |
| scene_info.h5_info.bundle_id | string(128) | false | 【iOS平台BundleID】 iOS平台BundleID |
| scene_info.h5_info.package_name | string(128) | false | 【Android平台PackageName】 Android平台PackageName |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| h5_url | string(256) | true | 【支付跳转链接】 h5\_url为拉起微信支付收银台的中间页面，服务商的H5页面内可通过访问该URL来拉起微信客户端，完成支付，h5\_url的有效期为5分钟。超过有效期则需要重新请求下单接口以获取新的h5\_url。<br>注意：微信支付会根据业务实际情况，调整支付跳转链接的长度和参数数量，因此该参数严禁篡改、拆分或截断。若需支付后跳转到指定页面，仅可在参数后拼接“redirect\_url”参数来指定回调页面，参考示例：[支付后返回指定页面](https://pay.weixin.qq.com/doc/v3/partner/4012085683.md#%E6%94%AF%E4%BB%98%E5%90%8E%E8%BF%94%E5%9B%9E%E6%8C%87%E5%AE%9A%E9%A1%B5%E9%9D%A2%EF%BC%9A)，禁止再拼接其他任何参数。 |
## 错误码

### 公共错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/partner/4012081726.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/partner/4012082324.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | APPID\_MCHID\_NOT\_MATCH | AppID和mch\_id不匹配 | 请确认AppID和mch\_id是否匹配，查询指引参考：[查询商户号绑定的APPID](https://pay.weixin.qq.com/doc/v3/partner/4013336007.md) |
| 400 | INVALID\_REQUEST | 无效请求 | 请根据接口返回的详细信息检查 |
| 400 | MCH\_NOT\_EXISTS | 商户号不存在 | 请检查商户号是否正确，商户号获取方式请参考[服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md) |
| 400 | PARAM\_ERROR | 参数错误 | 请根据接口返回的错误描述检查参数，参数需按API文档字段填写说明填写 |
| 401 | SIGN\_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求，参考：[如何生成签名](https://pay.weixin.qq.com/doc/v3/partner/4012365870.md) |
| 403 | NO\_AUTH | 商户无权限 | 请商户前往商户平台申请此接口相关权限，参考：[开发接入准备](https://pay.weixin.qq.com/doc/v3/partner/4012074917.md) |
| 403 | OUT\_TRADE\_NO\_USED | 商户订单号重复 | 请核实商户订单号是否重复提交 |
| 429 | FREQUENCY\_LIMITED | 频率超限 | 请求频率超限，请降低请求接口频率 |
| 500 | SYSTEM\_ERROR | 系统错误 | 系统异常，请用相同参数重新调用 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/partner/4012738604-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/partner/4012738604-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/partner/4012738604-go.md)


应答示例

> 200 OK

```
{
  "h5_url" : "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016121516420242444321ca0631331346&package=1405458241"
}

```
