【微信支付】API wx.requestPayment 详解

微信小程序支付API wx.requestPayment 是开发者在小程序内调起微信支付的核心接口。通过此接口，用户可以便捷、安全地完成支付操作。本文将深入解析该API的参数、使用场景及注意事项，帮助开发者快速掌握小程序支付开发。参考：wx.requestPayment(Object object)、Taro.requestPayment(option)、微信支付官方—小程序调起支付API。

一、wx.requestPayment 概述

1. 功能介绍

wx.requestPayment 是微信小程序提供的支付功能接口，用于发起支付请求。开发者通过调用此接口，可以在小程序内拉起微信支付界面，完成支付流程。

• 跨平台支持：支持多种微信客户端，包括 Windows 版、Mac 版、鸿蒙 OS 版等。
• 安全性高：支付数据通过微信支付后台校验和加密，确保交易安全。
• 便捷性强：与微信生态深度集成，用户体验流畅。

2. 接入前置条件

在调用 wx.requestPayment 前，需完成以下准备工作：

• 在微信公众平台开通微信支付功能。
• 配置支付参数，包括商户号、密钥等。
• 后端完成统一下单接口调用，并生成必要的支付参数（如 prepay_id）。

---

二、wx.requestPayment 的参数详解

1. 参数列表

以下是 wx.requestPayment 支持的参数：

参数名	类型	是否必填	说明
timeStamp	String	是	时间戳，从 1970 年 1 月 1 日 00:00:00 至今的秒数，表示当前时间。
nonceStr	String	是	随机字符串，不长于 32 位。推荐使用安全的随机数生成算法生成。
package	String	是	统一下单接口返回的 prepay_id 参数值，提交格式为 prepay_id=***。
signType	String	否	签名算法，默认为 MD5，支持 MD5、HMAC-SHA256 和 RSA（v3 版本接口适用）。
paySign	String	是	签名，确保支付参数未被篡改。具体签名算法请参考微信支付签名算法。
success	Function	否	支付成功的回调函数。
fail	Function	否	支付失败的回调函数。
complete	Function	否	接口调用完成后的回调函数，无论支付成功或失败都会执行。

---

2. 参数使用示例

以下是一个典型的 wx.requestPayment 参数示例：

wx.requestPayment({
  timeStamp: '1490840662', // 时间戳
  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS', // 随机字符串
  package: 'prepay_id=wx2017033010242291fcfe0db70013231072', // 预支付交易会话ID
  signType: 'MD5', // 签名类型
  paySign: 'C380BEC2BFD727A4B6845133519F3AD6', // 签名
  success(res) {
    console.log('支付成功', res);
  },
  fail(err) {
    console.error('支付失败', err);
  },
  complete(res) {
    console.log('支付完成，无论成功或失败都会调用', res);
  }
});

---

三、wx.requestPayment 的使用流程

1. 后端生成支付参数

小程序支付的关键在于后端调用微信支付的 统一下单接口，生成支付所需的 prepay_id 和相关参数。

统一下单接口的请求示例如下：

{
  "appid": "wx8888888888888888",
  "mch_id": "1900000109",
  "nonce_str": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
  "sign": "C380BEC2BFD727A4B6845133519F3AD6",
  "body": "商品描述",
  "out_trade_no": "1217752501201407033233368018",
  "total_fee": 1,
  "spbill_create_ip": "127.0.0.1",
  "notify_url": "https://your-backend-server/notify",
  "trade_type": "JSAPI",
  "openid": "wxd930ea5d5a258f4f"
}

成功调用后，微信支付后台返回的响应示例：

{
  "return_code": "SUCCESS",
  "result_code": "SUCCESS",
  "prepay_id": "wx2017033010242291fcfe0db70013231072"
}

---

2. 签名与数据返回

商户服务器需对返回的支付参数进行签名处理，并将签名后的数据发送至小程序客户端。

签名算法示例如下：

paySign = MD5(appId=wxd678efh567hg6787&nonceStr=5K8264ILTKCH16CQ2502SI8ZNMTM67VS&package=prepay_id=wx2017033010242291fcfe0db70013231072&signType=MD5&timeStamp=1490840662&key=商户密钥)

返回给小程序的完整参数：

{
  "timeStamp": "1490840662",
  "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
  "package": "prepay_id=wx2017033010242291fcfe0db70013231072",
  "signType": "MD5",
  "paySign": "22D9B4E54AB1950F51E0649E8810ACD6"
}

---

3. 小程序调用支付接口

小程序前端接收后端返回的数据后，直接调用 wx.requestPayment 发起支付。以下是整合后的代码：

wx.requestPayment({
  timeStamp: '1490840662',
  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
  package: 'prepay_id=wx2017033010242291fcfe0db70013231072',
  signType: 'MD5',
  paySign: '22D9B4E54AB1950F51E0649E8810ACD6',
  success(res) {
    console.log('支付成功', res);
  },
  fail(err) {
    console.error('支付失败', err);
  }
});

---

四、常见回调结果

1. 回调类型

wx.requestPayment 支持以下回调类型：

回调类型	errMsg 值	说明
成功	requestPayment:ok	调用支付成功。
用户取消	requestPayment:fail cancel	用户主动取消支付操作。
调用失败	requestPayment:fail	支付失败，通常包含详细失败原因。

2. 示例回调处理

wx.requestPayment({
  timeStamp: '1490840662',
  nonceStr: 'randomString123',
  package: 'prepay_id=wx2017033010242291fcfe0db70013231072',
  signType: 'MD5',
  paySign: 'generatedPaySign',
  success(res) {
    console.log('支付成功', res);
    // 进行后续业务逻辑处理，如更新订单状态
  },
  fail(err) {
    if (err.errMsg === 'requestPayment:fail cancel') {
      console.warn('用户取消支付');
    } else {
      console.error('支付失败', err);
    }
  },
  complete(res) {
    console.log('支付流程结束', res);
  }
});

---

五、注意事项

1. 签名一致性
   signType 必须与统一下单接口的签名类型保持一致，否则会导致支付失败。
2. 参数校验
   调用支付接口前，应确保后端生成的 timeStamp、nonceStr 等参数正确无误。
3. 云开发支持
   如果项目使用云开发，微信提供免鉴权的云开发微信支付接口，简化后端调用流程。
4. 用户体验
   在支付失败或取消支付后，需向用户提供清晰的提示信息，避免用户误操作。

推荐：

• JavaScript
• react
• vue

---