---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012078230.md"
title: "开发指引"
doc_id: 4012078230
---

>更新时间：2026.06.09

## 1、整体业务开发流程概览

- 商户通过调用[H5合单支付下单](https://pay.weixin.qq.com/doc/v3/merchant/4012556961.md)接口获取支付中间页(h5\_url)，然后商户在已配置H5支付域名的前端网页跳转该支付链接（如需支付后返回指定页面，可在H5支付链接后拼接redirect\_url参数），并唤起微信支付收银台。

- 当用户在收银台完成支付后点击完成按钮，或中途取消支付，页面会从收银台返回到拉起支付前的H5页面（若拉起收银台时有拼接redirect\_url参数将返回指定页面），此时商户后端需调用[查询合单订单API](https://pay.weixin.qq.com/doc/v3/merchant/4013421126.md)接口确认订单状态，并根据订单状态进行相应的业务逻辑处理（在商户页面向用户展示查询到的订单支付状态、在商户内部系统更新订单状态等）。如果订单支付成功，微信支付系统还会发送[合单订单支付成功回调通知](https://pay.weixin.qq.com/doc/v3/merchant/4013421143.md)给商户。具体的支付回调和查单的实现方案，商户可以参考[支付回调和查单实现指引](https://pay.weixin.qq.com/doc/v3/merchant/4012075249.md)。

- 最后商户可通过[下载交易账单](https://pay.weixin.qq.com/doc/v3/merchant/4013421176.md)进行对账。需要退款的订单，也可调用[退款接口](https://pay.weixin.qq.com/doc/v3/merchant/4013421148.md)完成退款。


![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/af777ac85b4029693110d5e35e973cfc.png)

## 2、详细步骤说明

### 2.1、商户下单

用户在商户H5页面操作下单后，商户需要通过调用[H5合单支付下单API](https://pay.weixin.qq.com/doc/v3/merchant/4012556961.md)接口生成订单并获取微信H5支付链接（h5\_url）。在这个过程中，商户必须做好安全校验，防止本次交易被不法分子利用。

- 当跨域请求不是[简单请求](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS#%E7%AE%80%E5%8D%95%E8%AF%B7%E6%B1%82)时，浏览器会发起Options[预检请求](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS#%E9%A2%84%E6%A3%80%E8%AF%B7%E6%B1%82)，此时商户后台需要支持Options请求且校验Origin头部，如果不在允许的白名单列表内，则返回403且不返回"Access-Control-Allow-\*"相关头部。

- 针对GET/POST的跨域下单请求，商户后台需要校验Origin头部是否合法且用户Cookie是否完备（若用户未登陆则先引导登陆商户站点），否则返回403且不返回"Access-Control-Allow-\*"相关头部。


安全标准规范流程图：

```mermaid
sequenceDiagram
    rect rgb(255,255,255)
        autonumber
        actor User as 用户
        participant Mch as 商户H5前端
        participant Mch2 as 商户后端
        participant WxPay as 微信支付系统

        User->>Mch: 用户操作下单
        Mch->>Mch2: 请求下单

        alt 浏览器 preflight 请求
            Mch->>Mch2: options请求

            note right of Mch: OPTIONS /api HTTP/1.1<br/>Access-control-request-headers: x-A,x-B<br/>Access-control-request-method: POST<br/>Origin: https://api.third.com<br/>Referer: https://api.third.com/
			Mch2->>Mch2: 判断Origin头部是否合法

            alt 判断Origin头部是否合法(是)
                Mch2-->>Mch: ：options请求正常响应
                note right of Mch: HTTP/1.1 200 OK<br/>Access-control-allow-credentials: true<br/>Access-control-allow-headers: x-A,x-B<br/>Access-control-allow-methods: POST, GET<br/>Access-control-allow-origin: https://api.third.com
            else 否
                Mch2-->>Mch: ：options请求异常响应
                note right of Mch: HTTP/1.1 403 Forbidden<br/>（no access-control-allow header）<br/>报错信息
            end

        end

        Mch->>Mch2: get/post请求
        note right of Mch: GET /api HTTP/1.1<br/>Host: api.shanghu.com<br/>Referer: https://api.third.com/1/2.html<br/>Origin: https://api.third.com<br/>Cookie: shanghu_uid=xxx:...

        Mch2->>Mch2: 判断Origin头部是否合法
        Mch2->>Mch2: 判断Cookie是否关联到商户站点已注册用户

        alt api.third.com合法且用户登录态有效(是)
            Mch2->>Mch2: 保存订单
            Mch2->>WxPay: 调用微信合单支付接口下单
            WxPay-->>Mch2: 返回跳转URL
            Mch2-->>Mch: ：请求下单正常响应（）
            note right of Mch: Access-Control-Allow-Origin: https://api.third.com<br/>Access-Control-Allow-Credentials: true
        else 否
            Mch2-->>Mch: ：请求下单异常响应
            note right of Mch: HTTP/1.1 403 Forbidden<br/>（no access-control-allow header）<br/>报错信息
        end
    end
```

注意：

- 商户需按照安全规范进行接入，若因未遵循规范接入而出现安全问题，财付通将根据[《微信支付服务协议》](https://pay.wechatpay.cn/index.php/public/apply_sign/protocol_dev)条款处理。

- 以上图示，仅为示例，只供参考。请商户自行确认是否实现了跨域访问白名单限制和用户登录态校验。


下单接口关键参数说明：

`combine_mchid`：合单发起方的商户号，需先申请发起合单支付权限，详细参考：[开发接入准备-步骤3](https://pay.weixin.qq.com/doc/v3/merchant/4015764448.md)。

`sub_order.mchid`：子单参与方的商户号，需先申请接收合单支付权限，详细参考：[开发接入准备-步骤3](https://pay.weixin.qq.com/doc/v3/merchant/4015764448.md)。

`combine_appid`：公众账号ID，合单发起方商户号 `combine_mchid` 和子单参与方商户号 `sub_order.mchid` 都需要绑定同一个 `combine_appid`，详细参考：[开发接入准备-步骤4和5](https://pay.weixin.qq.com/doc/v3/merchant/4015764448.md)。

`time_expire`：支付结束时间。若传递该参数，则用户只能在订单设置的支付结束时间 `time_expire` 之前进行支付，超过支付结束时间后，用户支付将收到："订单已超过商户设置的最晚支付成功时间，请重新发起支付"的提示，商户需对订单进行关单处理。若不传该参数，默认订单支付有效期为7天，用户可在7天内进行支付，超出7天，订单将被关闭。

`scene_info.payer_client_ip`：需要传真实的用户端IP，商户后端可以获取，具体参考：[获取用户ip指引](https://pay.weixin.qq.com/doc/v2/merchant/4011937139.md)

`h5_url`：支付跳转链接。调起支付时需要使用的参数， `h5_url` 有效期为5分钟，超过5分钟，商户需要使用原下单参数重新请求下单接口，获取新的 `h5_url`。

`profit_sharing`：订单分账标识，如果订单在支付成功后需要进行分账，必须传参数值为 `true`。如果无需分账，可以不传该参数，或传 `false`。

### 2.2、商户调起支付

商户调起支付前，请确保已在[商户平台](https://pay.weixin.qq.com/)配置好H5支付域名（只需合单发起方的商户号配置，合单参与方的商户号无需配置），只有[配置了H5支付域名](https://pay.weixin.qq.com/doc/v3/merchant/4013287193.md)的网页才能跳转H5支付链接（如需在支付后返回至指定页面，可在h5支付链接后面拼接上redirect\_url参数），调起微信支付页面。

```mermaid
%%{init: { "sequence": { "wrap": true, "wrapPadding": 10, "noteAlign": "left" } } }%%
sequenceDiagram
    rect rgb(255,255,255)
        autonumber
        actor User as 用户
        participant Mch as 商户H5前端
        participant Mch2 as 商户后端
        participant WxPay as 微信支付系统

        Mch->>WxPay: 跳转微信h5支付链接(如需支付完成返回指定页面可拼接redirect_url参数)
    end
```

### 2.3、用户支付

用户在微信收银台完成支付/取消支付，会返回商户调起支付时的页面，若调起支付时拼接了redirect\_url，则会返回指定的页面，此时商户需要调用[查询合单订单API](https://pay.weixin.qq.com/doc/v3/merchant/4013421126.md)接口确认订单状态，并根据订单状态展示支付结果。

如果用户支付成功，微信支付系统会向商户发送[合单订单支付成功回调通知](https://pay.weixin.qq.com/doc/v3/merchant/4013421143.md)，未收到回调时，商户可调用[查询合单订单API](https://pay.weixin.qq.com/doc/v3/merchant/4013421126.md)接口确认订单状态。具体实现方案商户可以参考[支付回调和查单实现指引](https://pay.weixin.qq.com/doc/v3/merchant/4012075249.md)。

若商户需要限制用户支付的时间，有以下两种方式：

1、下单时通过 `time_expire` 参数，设置订单的支付结束时间，超过设置的结束时间后，商户进行关单处理。

2、商户在自己的系统内进行倒计时，超过有效期，进行关单处理。

若因特殊原因需在用户可支付时间范围内关闭订单，商户可通过调用[查询合单订单API](https://pay.weixin.qq.com/doc/v3/merchant/4013421126.md)接口确认订单状态（请勿使用非合单支付的查单接口查询合单订单），若订单仍是未支付状态，商户可以调用[关闭合单订单API](https://pay.weixin.qq.com/doc/v3/merchant/4013421130.md)接口关单（关闭整个合单订单，而非关闭单个子单），关单后可以将订单当作失败终态处理。

```mermaid
%%{init: { "sequence": { "wrap": true, "wrapPadding": 10, "noteAlign": "left" } } }%%
sequenceDiagram
    rect rgb(255,255,255)
        autonumber
        actor User as 用户
        participant Mch as 商户H5前端
        participant Mch2 as 商户后端
        participant WxPay as 微信支付系统

        WxPay-->>Mch: 用户返回商户拉起支付页面或redirect_url 页面
        Mch->>Mch2: 查单确认订单状态
        Mch2->>WxPay: 调用微信合单支付查单接口
        WxPay-->>Mch2: 返回订单状态
        Mch2-->>Mch: 返回订单状态
        Mch-->>User: 根据订单状态展示支付结果

        alt 支付成功
            WxPay->>Mch2: 支付成功回调通知
        end

        alt 未收到支付成功回调
            Mch2->>WxPay: 调用微信合单支付查单接口轮询查单
            WxPay-->>Mch2: 返回订单状态

            alt 超过一定时间查单仍是未支付状态
                Mch2->>WxPay: 调用微信合单支付关单接口
                WxPay-->>Mch2: 返回关单结果
                Mch2->>Mch2: 订单当作失败终态处理
            end

        end
    end
```

### 2.4、商户对账

合单支付的订单账单是以子单为维度，每笔子单都会记录在各个子单商户账单内，需要各个子单商户自己进行下载。详细参考：[账单产品介绍](https://pay.weixin.qq.com/doc/v3/merchant/4013071215.md)

### 2.5、订单退款

合单支付的订单退款，无法通过合单商户订单号 `combine_out_trade_no` 退款，只能根据单个子单进行退款。详细参考：[退款产品介绍](https://pay.weixin.qq.com/doc/v3/merchant/4013071001.md)

## 3、合单支付订单状态流转图

```mermaid
%%{init: {'themeVariables':{'edgeLabelBackground':'#ffffff'}}}%%
stateDiagram-v2
    direction LR
    state "sub_orders.trade_state：NOTPAY（未支付）" as S2
    state "sub_orders.trade_state：SUCCESS（支付成功）" as S3
    state "sub_orders.trade_state：CLOSED（已关闭）" as S4

    [*] --> S2: 合单发起商户调用<br/>H5合单支付下单接口生成订单
    S2 --> S3: 用户支付成功
    S2 --> S4: 订单超过7天未支付<br/>微信侧进行自动关单
    S2 --> S4: 7天内合单发起商户可对未支付的订单调用关闭订单接口
    S3 --> [*]
    S4 --> [*]
    note right of S2
    	用户支付失败<br/>常见支付失败原因有：余额不足、用户风控、支付密码错误、超过商户设置的最晚支付时间（即下单设置的time_expire）等
    end note
```

1、商户调用[H5合单支付下单](https://pay.weixin.qq.com/doc/v3/merchant/4012556961.md)接口下单成功后，商户可以调用[查询合单订单](https://pay.weixin.qq.com/doc/v3/merchant/4013421126.md)接口来确认订单状态，详情请参考[支付回调和查单实现指引](https://pay.weixin.qq.com/doc/v3/merchant/4012075249.md)。

2、当订单状态处于未支付(sub\_orders.trade\_state：NOTPAY)时，用户可对订单进行支付，若用户支付失败，订单状态不变。

3、7天内商户可对无需继续支付的订单（例如用户超过商户系统内部规定的支付时间，或超过商户下单设置的最晚支付时间（time\_expire）的订单）调用[关闭合单订单接口](https://pay.weixin.qq.com/doc/v3/merchant/4013421130.md)，使订单关闭，或超过7天后由微信侧自动关单。关单后，订单状态会从未支付(sub\_orders.trade\_state：NOTPAY)流转为已关闭(sub\_orders.trade\_state：CLOSED)。

4、当用户成功支付订单时，订单状态会从未支付(sub\_orders.trade\_state：NOTPAY)流转为支付成功(sub\_orders.trade\_state：SUCCESS)。

5、当订单状态为支付成功(sub\_orders.trade\_state：SUCCESS)时，如果用户需要退款，商户可调用[申请退款接口](https://pay.weixin.qq.com/doc/v3/merchant/4013421148.md)(仅支持支付成功后1年内的订单)，退款申请成功后，退款状态可通过[查询退款单接口](https://pay.weixin.qq.com/doc/v3/merchant/4013421156.md)进行确认。

6、以下两个状态为终态

- sub\_orders.trade\_state：CLOSED

- sub\_orders.trade\_state：SUCCESS