@cordova-ohos/cordova-plugin-alipay-v2

v2.0.1

Published

7 days ago

Cordova alipay Plugin

0High
0Medium
0Low

cordova alipay-v2 ecosystem:cordova cordova-openharmony

cordova-plugin-alipay-v2

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-plugin-alipay-v2

简介

cordova-plugin-alipay-v2 是一款基于 Cordova 框架的支付宝支付集成插件，适配支付宝开放平台接口规范，支持 Android、iOS 和 OHOS 平台。通过该插件，开发者可快速在 Cordova 混合应用中集成支付宝支付功能，包括订单创建、支付结果回调、支付状态查询等核心能力，满足电商、O2O、服务类应用的支付场景需求，且兼容支付宝客户端支付与 H5 支付两种模式，确保支付流程稳定可靠。本文档主要说明在 OpenHarmony 系统中的应用。

核心特性

平台适配：支持 Android、iOS 和 OHOS 平台，遵循各平台支付宝 SDK 规范，确保跨平台一致性。
多支付模式：支持「支付宝客户端支付」（推荐，体验优）和「H5 支付」（备用，无客户端时自动降级）。
完整支付流程：覆盖订单签名、支付发起、结果回调、异常处理全链路，无需额外开发冗余逻辑。
支付状态同步：支付结果实时回调，支持同步通知与异步通知结合，确保订单状态一致性，避免漏单、错单。
签名安全保障：支持本地签名（测试环境）和服务端签名（生产环境），规避签名信息泄露风险，符合金融级安全要求。
错误处理机制：提供明确的错误码与描述，覆盖网络异常、支付取消、订单无效、签名错误等常见场景，便于问题定位。
轻量化设计：插件体积小（仅～80KB），无冗余依赖，不影响应用启动速度，适配各类 Cordova 混合应用。

前置依赖

支付宝开放平台账号：需在支付宝开放平台注册开发者账号，创建应用并开通「手机网站支付」或「App 支付」能力。
应用密钥配置：需生成应用公钥/私钥对（推荐使用 RSA2 算法），并在支付宝开放平台配置公钥，获取 AppID（应用唯一标识）。
Cordova 环境：项目需基于 Cordova 10.0.0+ 框架构建，确保 OHOS 平台已添加到 Cordova 项目中。
依赖插件：无需额外 Cordova 插件依赖，支付宝官方 SDK 会在插件安装时自动集成。

环境准备

在集成插件前，需完成以下环境配置（关键步骤，否则会导致支付失败）：

1. 支付宝开放平台配置

登录支付宝开放平台，进入「控制台 → 应用管理 → 创建应用」，选择「App 应用」类型。
应用创建后，在「能力列表」中添加「App 支付」或「手机网站支付」能力，提交审核（审核通常 1-3 个工作日）。
审核通过后，进入「应用信息 → 开发设置」，配置以下信息：
- 应用公钥：上传使用 RSA2 算法生成的应用公钥（需与代码中私钥匹配）。
- OHOS 平台：配置 OHOS 相关参数，确保插件与支付宝 SDK 正常通信。

支持平台

Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+

下载安装

通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库、GitCode 仓库安装，也可指定版本安装，仅需针对 OHOS 平台安装时添加对应参数。

1. 基础安装（推荐）

使用 hcordova 命令化工具安装，自动集成支付宝 SDK 与平台基础配置：

# 安装 hcordova 命令化工具
npm install -g hcordova

# 全平台安装
hcordova plugin add cordova-plugin-alipay-v2

# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-alipay-v2 --platform ohos

2. 安装指定版本

如需兼容特定支付宝 SDK 版本或 Cordova 版本，可指定插件版本安装（仅 OHOS 平台）：

# 指定版本安装（仅 OHOS 平台）
hcordova plugin add [email protected] --platform ohos

3. 从 GitCode 仓库安装

如需测试最新开发功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：

# 仅安装到 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-alipay-v2.git --platform ohos

# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-alipay-v2.git@develop --platform ohos

4. 离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-alipay-v2）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-alipay-v2 --platform ohos

5. 安装后验证

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

6. 卸载插件

# 全平台卸载
hcordova plugin remove cordova-plugin-alipay-v2

# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-alipay-v2 --platform ohos

约束与限制

应用配置：需完成支付宝开放平台应用审核与密钥配置，否则无法发起支付请求。
签名要求：生产环境必须使用服务端签名，避免本地签名导致的私钥泄露风险，签名算法推荐使用 RSA2。
平台配置：OHOS 平台需严格按照要求完成 scheme 声明、依赖配置及 buildOption 设置，否则会导致支付失败或回调异常。
支付模式：H5 支付需服务端配合生成 H5 支付链接，无支付宝客户端时方可正常降级使用。

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |

在以下版本中已测试通过：

| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |

权限要求

需授予应用网络访问权限（用于与支付宝服务器通信、获取支付参数及回调结果），插件自动适配 OHOS 平台基础权限，无需额外手动配置；需按要求配置 scheme，确保跳转支付宝客户端正常。

使用示例

示例 1：发起支付宝支付

订单信息由服务端生成并签名，客户端调用插件支付接口，接收支付结果并处理，适配 OHOS 平台回调逻辑。

注意：以下 payInfo 字符串仅作为格式参考。在实际生产环境中，此字符串必须由您的服务器根据您的实际 app_id 和签名生成。

// 订单信息由服务端生成（含签名，生产环境推荐服务端签名）
function openAlipay() {
   var payInfo = "alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=YOUR_APP_ID&biz_content=YOUR_BIZ_CONTENT&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=YOUR_NOTIFY_URL&sign=YOUR_SIGN_STRING&sign_type=RSA2&timestamp=2025-10-13+18%3A02%3A57&version=1.0";
    cordova.plugins.alipay.payment(payInfo,function(e){
        if(e.resultStatus == 9000) {
            // 支付成功，可调用服务端接口验证结果
            document.getElementById("alipayInfo").innerHTML = "支付成功";
        }
        if(e.resultStatus == 8000) {
            // 支付宝正在处理，需后续通过异步通知确认
            document.getElementById("alipayInfo").innerHTML = "支付宝正在处理";
            return;
        }
        // 支付取消、订单无效等状态，可根据 resultStatus 进一步处理
    },function(e){
        // 支付失败（网络异常、签名错误等）
        document.getElementById("alipayInfo").innerHTML = "支付失败";
        return;
    });
}

使用说明

支付流程说明

支付宝支付完整流程需客户端与服务端配合，确保订单安全与状态一致，核心步骤如下：

客户端发起订单请求：用户在客户端选择商品后，向商户服务端发起创建订单请求（携带商品 ID、金额等信息）。
服务端创建并签名订单：
- 服务端生成唯一商户订单号（out_trade_no），避免重复订单。
- 构造支付宝订单参数（biz_content），包含订单金额、描述、超时时间等信息。
- 使用应用私钥进行签名（RSA2 算法），生成完整的支付参数（payInfo）。
- 将包含签名的完整支付参数返回给客户端。
客户端发起支付：客户端调用插件 payment() 方法，传入服务端返回的 payInfo，触发支付宝支付。
用户完成支付：
- 若设备已安装支付宝客户端，直接跳转至客户端完成支付，体验更优。
- 若未安装支付宝客户端，自动降级为 H5 支付（需服务端配合生成 H5 支付链接）。
支付结果回调：
- 同步回调：支付完成后跳转回客户端，插件通过 successCallback 返回同步结果（仅作为参考，不可作为订单确认依据）。
- 异步回调：支付宝服务器向商户服务端的 notify_url 推送支付结果（可靠，推荐作为订单状态确认的核心依据）。
客户端验证结果：客户端收到同步结果后，需调用商户服务端接口，验证支付结果的真实性，避免伪造结果。
订单状态更新：服务端验证支付结果通过后，更新本地订单状态（如“已支付”），并向客户端返回最终确认结果，完成整个支付流程。

平台配置细节

插件安装后需完成 OHOS 平台专属配置，否则可能导致支付失败、无法跳转支付宝客户端或回调异常，具体步骤如下：

OHOS 平台配置

在 App module 的 module.json5 中添加 scheme 声明，用于跳转支付宝客户端后回调应用：

"querySchemes": [
   "alipays"
]

修改项目中的 oh-package.json5 文件，在 dependencies 中添加支付宝 SDK 依赖项：

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "@cashier_alipay/cashiersdk": "^15.8.35"
  }
}

在 build-profile.json5 中找到 buildOption 配置，添加 "useNormalizedOHMUrl": true，解决插件依赖适配问题：

"buildOption": {
    "strictMode": {
    "useNormalizedOHMUrl": true
    }
}

错误码说明（核心）

支付过程中常见错误码及处理建议，便于快速定位问题：

9000：支付成功，需调用服务端接口验证结果真实性。
8000：支付宝正在处理，需等待异步通知确认订单状态。
4000：支付失败，可能是订单参数错误、签名错误或网络异常。
6001：用户取消支付，可提示用户重新发起支付。
6002：网络异常，需检查设备网络连接，并重试支付。

新增特性

无新增特性，保持原生插件核心支付功能，适配 OpenHarmony 平台运行需求，完善 OHOS 平台专属配置说明、回调逻辑适配，确保支付流程在 OpenHarmony 设备上稳定可靠，兼容支付宝客户端与 H5 支付模式。

目录结构

cordova-plugin-alipay-v2/
├── src/                          # 源代码目录
│   └── main/                     # 主要源代码
│       ├── cpp/                  # C++ 原生代码
│       │   └── alipay/           # 支付宝支付模块
│       │       ├── alipay.cpp    # 支付宝支付 C++ 实现
│       │       └── alipay.h      # 支付宝支付头文件
│       └── ets/                  # ArkTS 代码
│           └── components/       # 组件目录
│               └── AlipayAction/ # 支付宝支付动作组件
│                   └── AlipayAction.ets  # ets 支付宝支付实现
├── www/                          # Web 资源目录
│   └── js_alipay.js              # 暴露给 Cordova 的 JS API
├── LICENSE                       # 开源许可证文件
├── OAT.xml                       # OpenHarmony 审核配置文件
├── package.json                  # Node.js 包配置文件
├── plugin.xml                    # Cordova 插件描述文件（核心配置）
└── README.md                     # 项目说明文档

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。

官方资源

Android 和 iOS：cordova-plugin-alipay-v2 官方指南
GitCode 仓库：CPF-Cordova/cordova-plugin-alipay-v2