Taro 支付 API 文档详解

概述

本文档详细讲解了 Taro 框架中三个核心的支付 API：requestPayment、requestOrderPayment和faceVerifyForPay，基于官方文档提供深度分析和实用指导。

---

1. Taro.requestPayment - 基础支付接口

1.1 基本信息

• 功能描述：发起微信支付的标准接口
• 适用场景：普通小程序支付功能
• 支持平台：微信小程序、H5、React Native、HarmonyOS
• 官方文档：微信支付接口文档

1.2 接口定义

Taro.requestPayment(option: Option): Promise<TaroGeneral.CallbackResult>

1.3 参数详解

参数名	类型	必填	说明	示例
timeStamp	string	是	时间戳（秒级）	“1600000000”
nonceStr	string	是	32 位随机字符串	“5K8264ILTKCH16CQ2502SI8ZNMTM67VS”
package	string	是	统一下单返回的 prepay_id	“prepay_id=wx20180101…”
signType	keyof SignType	否	签名算法	“MD5” / “RSA”
paySign	string	是	签名结果	根据签名规则生成

1.4 SignType 签名算法

• MD5：微信支付 v2 版本
• HMAC-SHA256：微信支付 v2 版本
• RSA：微信支付 v3 版本

1.5 使用示例

Taro.requestPayment({
  timeStamp: '1600000000',
  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
  package: 'prepay_id=wx20180101...',
  signType: 'MD5',
  paySign: 'C380BEC2BFD727A4B6845133519F3AD6',
  success: function (res) {
    // 支付成功处理
    console.log('支付成功', res);
  },
  fail: function (res) {
    // 支付失败处理
    console.log('支付失败', res);
  },
});

---

2. Taro.requestOrderPayment - 自定义交易组件支付

2.1 基本信息

• 功能描述：创建自定义版交易组件订单并发起支付
• 适用场景：仅适用于接入自定义版交易组件的小程序
• 特殊说明：普通小程序请使用requestPayment
• 支持平台：微信小程序、H5、React Native、HarmonyOS

2.2 接口定义

Taro.requestOrderPayment(option: Option): Promise<TaroGeneral.CallbackResult>

2.3 参数详解

参数名	类型	必填	说明	特殊要求
timeStamp	string	是	时间戳	同 requestPayment
nonceStr	string	是	随机字符串	同 requestPayment
package	string	是	prepay_id	同 requestPayment
orderInfo	any	否	订单信息	需要校验的场景必填
extUserUin	string	否	外部 APP 用户 ID	跨平台支付时使用
signType	keyof SignType	否	签名算法	同 requestPayment
paySign	string	是	签名	同 requestPayment

2.4 orderInfo 结构

根据自定义版交易组件文档，orderInfo 包含订单校验信息。

2.5 使用示例

Taro.requestOrderPayment({
  orderInfo: {
    order_id: '123456789',
    sku_list: [
      {
        sku_id: 'sku123',
        sku_cnt: 1,
      },
    ],
  },
  timeStamp: '1600000000',
  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
  package: 'prepay_id=wx20180101...',
  signType: 'MD5',
  paySign: 'C380BEC2BFD727A4B6845133519F3AD6',
  success(res) {
    console.log('订单支付成功', res);
  },
  fail(res) {
    console.log('订单支付失败', res);
  },
});

---

3. Taro.faceVerifyForPay - 人脸支付验证

3.1 基本信息

• 功能描述：支付场景下的人脸识别验证
• 适用场景：需要高安全级别的支付验证
• 支持平台：微信小程序、H5、React Native、HarmonyOS
• 官方文档：人脸支付验证文档

3.2 接口定义

Taro.faceVerifyForPay(option: any): Promise<any>

3.3 参数说明

由于官方文档中参数结构较为灵活，建议参考微信官方文档获取最新的参数要求。

3.4 使用示例

Taro.faceVerifyForPay({
  // 根据具体业务需求配置参数
  name: '用户姓名',
  idCardNumber: '身份证号码',
  // 其他验证参数
})
  .then((res) => {
    console.log('人脸验证成功', res);
  })
  .catch((err) => {
    console.log('人脸验证失败', err);
  });

---

4. API 对比与选择指南

4.1 功能对比表

特性	requestPayment	requestOrderPayment	faceVerifyForPay
主要用途	标准支付	自定义交易组件支付	人脸验证支付
适用场景	普通小程序	电商小程序	高安全支付
参数复杂度	简单	中等	复杂
前置条件	统一下单	自定义交易组件	实名认证
用户体验	快速	完整购物流程	安全验证

4.2 选择建议

4.2.1 使用 requestPayment 的场景

• 普通小程序支付功能
• 简单的商品购买
• 不需要复杂订单管理

4.2.2 使用 requestOrderPayment 的场景

• 已接入微信小商店
• 需要完整的订单管理
• 复杂的商品 SKU 管理

4.2.3 使用 faceVerifyForPay 的场景

• 大额支付验证
• 敏感操作验证
• 符合监管要求

---

5. 开发注意事项

5.1 通用注意事项

1. 签名安全：paySign 必须在服务端生成，禁止在前端生成
2. 参数校验：前端需要校验必填参数完整性
3. 错误处理：完善的失败回调处理
4. 用户体验：支付过程中显示加载状态

5.2 常见问题

• timeStamp 格式：必须是字符串类型的秒级时间戳
• nonceStr 长度：不能超过 32 个字符
• package 格式：必须以"prepay_id="开头
• 签名算法：根据微信支付版本选择正确的 signType

5.3 调试建议

1. 使用微信开发者工具进行调试
2. 检查服务端返回的 prepay_id 是否有效
3. 验证签名算法和密钥配置
4. 查看微信支付商户平台日志

---

6. 最佳实践

6.1 支付流程设计

// 完整的支付流程示例
async function handlePayment(orderData) {
  try {
    // 1. 创建订单
    const orderResult = await createOrder(orderData);

    // 2. 获取支付参数
    const paymentParams = await getPaymentParams(orderResult.orderId);

    // 3. 发起支付
    const payResult = await Taro.requestPayment({
      ...paymentParams,
      success: (res) => {
        // 支付成功处理
        handlePaymentSuccess(res);
      },
      fail: (res) => {
        // 支付失败处理
        handlePaymentFail(res);
      },
    });

    return payResult;
  } catch (error) {
    console.error('支付流程错误', error);
  }
}

6.2 错误处理策略

• 网络错误：提示用户检查网络
• 参数错误：记录日志并提示重新操作
• 支付失败：根据错误码给出具体提示
• 用户取消：友好提示，可引导重新支付

---

总结

• 核心价值：这三个 API 覆盖了小程序支付的主要场景，从基础支付到高级验证
• 关键要点：
  1. 根据业务场景选择合适的 API
  2. 严格遵循参数格式要求
  3. 重视安全性和用户体验
  4. 完善的错误处理机制
• 后续建议：
  • 深入学习微信支付开发文档
  • 了解最新的支付安全规范
  • 关注 Taro 框架的版本更新

相关资源

• 微信支付开发文档
• Taro 支付 API 文档
• 微信小程序支付指南