@cordova-ohos/cordova-plugin-adam-alipay

v2.0.5

Published

6 days ago

Cordova alipay Plugin

0High
0Medium
0Low

cordova adam-alipay ecosystem:cordova cordova-openharmony

cordova-plugin-adam-alipay

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

cordova-plugin-adam-alipay

简介

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

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

支持平台

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

下载安装

通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。

从 npm 安装（推荐）

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

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

# 仅安装到 OHOS 平台（推荐稳定版）
hcordova plugin add cordova-plugin-adam-alipay --platform ohos

安装指定版本

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

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

从 GitCode 仓库安装

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

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

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

离线安装（本地包）

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

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

安装后验证

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

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

卸载

# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-adam-alipay 

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

约束与限制

前置依赖：需拥有支付宝开放平台账号，创建应用并开通对应支付能力，配置应用密钥与 AppID；
依赖插件：无额外 Cordova 插件依赖，支付宝官方 SDK 会在插件安装时自动集成。
平台配置：OHOS 平台需完成 scheme 声明、依赖配置及 buildOption 设置，否则会导致支付失败或回调异常。
签名要求：生产环境需使用服务端签名，避免本地签名导致的私钥泄露风险；签名算法推荐使用 RSA2。

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | 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：发起支付宝支付

订单信息由服务端生成，客户端调用插件支付接口，接收支付结果并处理。

// 订单信息有服务端生成
function openAlipay2() {
    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";
    Alipay.pay(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;
    });
}

使用说明

前置依赖

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

环境准备

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

1. 支付宝开放平台配置

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

快速上手

插件使用流程遵循支付宝支付标准流程：服务端创建订单 → 生成支付签名 → 客户端发起支付 → 接收支付结果 → 服务端验证结果，参考上述使用示例即可快速集成。

支付流程说明

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

客户端发起订单请求：用户在客户端选择商品后，向商户服务端发起创建订单请求（携带商品 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",
    "@cordova-ohos/ohos": "file:../cordova"
  }
}

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

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

新增特性

无新增特性，保持原生插件核心支付功能，适配 OpenHarmony 平台运行需求，完善 OHOS 平台专属配置说明，确保支付流程在 OpenHarmony 设备上稳定可靠。

目录结构

cordova-plugin-adam-alipay/
├── src/main/                          # 主要源代码目录
│   ├── cpp/adam/                      # C++ 实现层
│   │   ├── Alipay.cpp                 # 支付宝支付功能的 C++ 实现
│   │   └── Alipay.h                   # 对应的头文件声明
│   ├── ets/components/AlipayAction/   # ets 组件层
│   │   └── AlipayAction.ets           # 支付宝支付的 eTS 组件封装
├── www/                               # Web 前端资源
│   └── alipay.js                      # 提供给 Cordova WebView 调用的 JS 接口
├── LICENSE                            # 开源许可证文件
├── OAT.xml                            # 开源审查（OAT）配置文件
├── package.json                       # Node.js 包描述文件
├── plugin.xml                         # Cordova 插件配置文件
└── README.md                          # 项目说明文档

贡献代码

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

许可证

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

官方资源

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