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

v2.0.0

Published

a month ago

Cordova alipay Plugin

0High
0Medium
0Low

cordova alipay-v2 ecosystem:cordova cordova-openharmony

cordova-plugin-alipay-v2

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

核心特性

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

前置依赖

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

环境准备

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

1. 支付宝开放平台配置

登录支付宝开放平台，进入「控制台 → 应用管理 → 创建应用」，选择「App 应用」类型
应用创建后，在「能力列表」中添加「App 支付」或「手机网站支付」能力，提交审核（审核通常 1-3 个工作日）
审核通过后，进入「应用信息 → 开发设置」，配置以下信息：

应用公钥：上传使用 RSA2 算法生成的应用公钥（需与代码中私钥匹配）
OHOS 平台：配置OHOS相关参数

安装指南

1. 基础安装（推荐）

通过 npm 安装最新稳定版，自动集成支付宝 SDK 与平台配置：

# 安装hcordova
npm install -g hcordova

# 安装插件
hcordova plugin add cordova-plugin-alipay-v2 --platform ohos

2. 安装指定版本

如需兼容特定支付宝 SDK 版本或 Cordova 版本，可指定插件版本：

# 指定版本安装
hcordova plugin add [email protected] --platform ohos

3. 从 GitCode 安装

如需测试最新功能或修复，可从 GitCode 仓库安装开发分支：

hcordova plugin add https://gitcode.com/OpenHamrony-Cordova/cordova-plugin-alipay-v2.git --platform ohos

4. 卸载插件

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

//指定HamronyOS平台卸载
hcordova plugin remove cordova-plugin-alipay-v2 --platform ohos

快速上手

插件使用流程遵循支付宝支付标准流程：服务端创建订单 → 生成支付签名 → 客户端发起支付 → 接收支付结果 → 服务端验证结果，以下为基础使用示例。

1. 核心示例：发起支付宝支付

//订单信息有服务端生成
function openAlipay() {
    var payInfo = "alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2017041306680984&biz_content=%7B%22body%22%3A%22%E8%B4%AD%E4%B9%B0%E7%9F%AD%E4%BF%A1%22%2C%22out_trade_no%22%3A%2225101364977878617%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22subject%22%3A%22%E8%B4%AD%E4%B9%B0%E7%9F%AD%E4%BF%A1%22%2C%22timeout_express%22%3A%2230m%22%2C%22total_amount%22%3A%22200%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=https%3A%2F%2Fceshi.tongecn.com%2Fcorp%2FalipayNotify.jsp&sign=L17%2FIxubmoTHwIC6P%2BWJWJFy45HzqZCZ5ODUz0el1UzcitPFMlkUP8T8TfKhVGmDMXUC0%2FNnWvahb%2FmaB0rXJajqekG89tx1AegO7TFcw45zvkJJUhoDqL%2F6aSM2SReAIaac0sq7vElgQEMNVbDcMdLmJFFwgNWO%2F%2BiuIfysw4RNiZlfOM6nnCgFjhjkBstWuC6BeD%2BGpJhwPYvJIH7Rl0Gv07AN3D15Vclxi%2FvMZOjsH5Ileq3Dmgfhm1TNcGqIjOHFvLmkA1UdyieGA10yRpvP74SfXJFLwbN2F7RxtJDDcck0GBff4TOGZmS3dRdOVeqN5WcD%2F348HeKw8WszVg%3D%3D&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;
        }

    },function(e){
        document.getElementById("alipayInfo").innerHTML = "支付失败";
        return;
    });
}

支付流程说明

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

客户端发起订单请求：用户在客户端选择商品后，向商户服务端发起创建订单请求（携带商品 ID、金额等信息）
服务端创建并签名订单：

服务端生成唯一商户订单号（out_trade_no）
构造支付宝订单参数（biz_content），使用应用私钥进行签名（RSA2 算法）
将包含签名的完整支付参数返回给客户端

客户端发起支付：客户端调用插件 payment() 方法，传入服务端返回的支付参数，触发支付宝支付
用户完成支付：

若安装支付宝客户端，直接跳转至客户端完成支付
若未安装，可降级为 H5 支付（需服务端配合生成 H5 支付链接）

支付结果回调：

同步回调：支付完成后跳转回客户端，插件通过 successCallback 返回客户端同步结果
异步回调：支付宝服务器向商户服务端 notify_url 推送支付结果（可靠，推荐作为订单状态确认依据）

客户端验证结果：客户端收到同步结果后，需调用商户服务端接口，验证支付结果真实性（避免伪造结果）
订单状态更新：服务端验证支付结果通过后，更新本地订单状态，并向客户端返回最终确认结果

平台配置细节

插件安装后需完成以下平台专属配置，否则可能导致支付失败或回调异常。

OHOS 平台配置

在开发者的 App module 的 module.json5 里加入下方scheme声明：

"querySchemes": [
   "alipays"
]

修改项目中的oh-package.json5文件，在dependencies中加入微信 alipaysdk 的依赖项：

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

支付宝支付插件引起的，在build-profile.json5中增加找到buildOption配置选项，增加"useNormalizedOHMUrl": true，如下：

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

许可证

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

参考资源

Android和iOS：cordova-plugin-alipay-v2 官方指南
GitCode 仓库：OpenHarmony-Cordova/cordova-plugin-alipay-v2
支付宝SDK：[提交 Issue](https://ohpm.HarmonyOS.cn/#/cn/detail/@cashier_alipay%2Fcashiersdk)