---
title: WeChat Pay
pageComponent:
  name: PaymentMethodsTitle
  paymentMethod: WeChat Pay
permalink: /notes/zh/paymentMethods/WeChatPay/
createTime: '2025/06/24 11:04:19'
description: >-
  WeChat Pay 是微信支付方式，适用于中国地区的PC端和移动端支付。主要特点包括：显示微信支付二维码、支持用户扫码支付、实时更新支付状态。在PC端，用户通过扫描二维码完成支付；在移动端，根据浏览器环境调起微信支付或显示二维码。使用时需确保域名已加入微信H5支付授权，并设置 Referer 请求头。
---

<v4-PaymentMethodsFeatures/>

## 支付域名授权

根据微信要求，需要将商户的域名加入微信的 H5 支付授权域名中。并且需设置 Referer 请求头。
我们默认将您的申请开户申报的域名加入微信的 H5 支付授权域名中。

如果您需要添加其他域名， 请您将相关申请信息发送到`acquire-risk@pingpongx.com`并抄送`acquire-ts@pingpongx.com`。

**申请材料：**
1. 商户Client ID
2. 商户授权域名

## 支付场景说明

### PC端支付
- 显示微信支付二维码
- 用户使用微信扫码完成支付
- 页面实时显示支付状态更新

### 移动端支付
1. **微信内浏览器**：暂不支持直接调起微信支付，根据微信要求需要JSAPI调用。
2. **微信外浏览器**：
   - iOS：跳转到微信客户端
   - Android：显示二维码或尝试调起微信
   - 其他情况：显示二维码供扫码支付

:::danger 提示
- 您的域名必须加入微信 H5 支付授权域名。
- 微信对Referer 的要求严格，请务必设置 Referer 请求头。
- 确保用户通过页面跳转进入支付页面，而非直接访问支付链接
::: 

## 常见问题

### 错误提示："商家参数格式有误，请联系商家解决"

**问题原因：**
- Referer 请求头为空或缺失
- 用户直接访问支付链接，未通过页面跳转

**解决方案：**
1. 确保用户通过页面跳转进入支付页面，而非直接访问支付链接
2. App 内 WebView 需手动设置 Referer 请求头：
   ```java
   Map<String, String> extraHeaders = new HashMap<>();
   extraHeaders.put("Referer", "https://你的授权域名");
   ```

### 错误提示："商家存在未配置的参数，请联系商家解决"

**问题原因：**
- 当前网页域名与微信后台配置的 H5 支付授权域名不一致

**解决方案：**
1. 联系我们确认授权域名是否正确
2. 修改或添加正确的授权域名

### 错误提示："支付请求已失效，请重新发起支付"

**问题原因：**
- 支付链接超过 5 分钟有效期

**解决方案：**
- 重新调用支付接口生成新的支付链接

### 错误提示："请在微信外打开订单，进行支付"

**问题原因：**
- 在微信客户端内使用了 H5 支付方式

**解决方案：**
- 微信内环境应使用 JSAPI 支付
- 引导用户在外部浏览器中打开支付页面

### 错误提示："签名验证失败"或"系统繁忙"

**问题原因：**
1. 多个微信账号访问同一支付链接
2. 回调 URL 编码不正确

**解决方案：**
1. 为每个用户生成独立的支付链接
2. 确保回调 URL 参数正确编码

### 错误提示："由于商家传入的H5交易参数有误"

**问题原因：**
- 客户端 IP 地址错误（如使用 127.0.0.1）

**解决方案：**
- 使用真实的客户端 IP 地址

### Referer 相关配置说明

微信 H5 支付对 Referer（HTTP 请求头中的来源域名）有严格要求：

**Referer 作用：**
微信服务器通过 Referer 头部判断当前网页的来源域名，是否与微信商户平台中配置的 H5 支付授权域名一致。

**常见 Referer 问题解决方案：**

| 问题类型           | 具体表现                          | 解决方案                            |
|----------------|-------------------------------|---------------------------------|
| **Referer 为空** | 直接访问支付链接或 WebView 未设置 Referer | 确保通过页面跳转访问；WebView 手动设置 Referer |
| **域名不匹配**      | 当前域名与授权域名不一致                  | 在微信商户平台添加或修改授权域名                |
| **WebView 配置** | App 内 H5 无法调起支付               | 手动添加 Referer Header             |