一、 摘要与引言

在移动应用生态中，安全、便捷、可信的支付能力是构建商业闭环的基石。美寇商城作为基于HarmonyOS NEXT 5.0构建的电商应用，集成华为支付（HUAWEI IAP Kit）是实现商业价值、提升用户体验的战略选择。本文将以美寇商城项目为基础，详述在鸿蒙5.0（API 12+）环境下，遵循官方架构与开发规范，接入华为支付的全流程，并提供符合规范的代码示例与设计图。官方开发指南，确保方案的规范性与实践性。

接入华为支付将为美寇商城带来核心价值：

• 体验升级：提供与系统深度融合的原生支付界面，支持指纹、面容等生物识别，实现一键安全支付。
• 生态整合：借助华为庞大的用户基数与统一的支付账户体系，降低用户支付门槛，提升交易转化率。
• 安全保障：交易过程由华为支付服务保障，资金流安全可靠，降低商户的合规与技术风险。

二、 系统架构设计

华为支付集成采用典型的分层与模块化设计，与商城订单、商品业务解耦，确保高内聚、低耦合。

架构说明：

1. 表现层：商城商品页、订单确认页。当发起支付时，通过IAP Kit唤起系统级或应用内支付界面。
2. 业务逻辑层：
   • OrderService：负责管理商品、生成订单业务数据。
   • PayService：支付核心模块，串联起本地订单创建、服务器交互、IAP Kit调用和支付结果校验。
3. 能力层：
   • IAP Kit：华为支付核心SDK，提供商品查询、创建购买、消耗商品等原子化接口。
   • Network Kit：用于与美寇商城服务器通信，完成订单同步与支付结果校验。
4. 服务端：
   • 美寇商城服务器：至关重要，负责生成唯一商户订单、接收客户端支付结果并向华为服务器进行最终校验，防止伪造支付。
   • 华为IAP服务器：处理真实的支付交易与凭证签发。

三、 开发全流程与核心代码

3.1 开发前置准备

1. 环境与配置：在module.json5中声明必要的网络权限。

   {
     "module": {
       "requestPermissions": [
         {
           "name": "ohos.permission.INTERNET"
         }
       ]
     }
   }
   

2. 依赖引入：在oh-package.json5中添加IAP Kit依赖。

   {
     "dependencies": {
       "@ohos/iap" : "2.1.0" // 使用最新版本
     }
   }
   

3. 商户侧配置：在华为开发者联盟为美寇商城应用开启“华为支付”服务，并在后台配置商品信息（如商品ID、类型、价格）。应用包名、签名证书指纹必须与提交审核时一致。

3.2 核心支付流程代码实现

下图清晰地展示了从用户点击“购买”到完成交易的完整时序，特别是客户端与服务器端的协同校验过程：

以下是支付核心服务类 PayService.ets 的ArkTS实现：

import { iap, ConsumeOwnPurchaseData, OwnedPurchase, PurchaseResultInfo, ProductInfo } from '@ohos/iap';
import { BusinessError } from '@ohos.base';
import { http } from '@ohos/net.http';
import { Logger } from '@ohos/base'; // 假设有日志工具

export class PayService {
  private static instance: PayService;
  private iapClient: iap.IapClient | null = null;
  // 美寇商城服务器接口地址
  private serverCreateOrderUrl: string = 'https://api.meikou.com/order/create';
  private serverVerifyPayUrl: string = 'https://api.meikou.com/pay/verify';

  static getInstance(): PayService {
    if (!PayService.instance) {
      PayService.instance = new PayService();
      PayService.instance.initIapClient();
    }
    return PayService.instance;
  }

  // 初始化IAP客户端
  private async initIapClient(): Promise<void> {
    try {
      // 环境参数，正式环境使用 iap.Env.PROD
      this.iapClient = await iap.getIapClient(iap.Env.PROD);
      Logger.info('[PayService] IAP Client 初始化成功.');
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      Logger.error(`[PayService] IAP Client 初始化失败: Code=${err.code}, Message=${err.message}`);
    }
  }

  // 主支付方法
  async purchaseProduct(productId: string, productName: string, amount: number): Promise<boolean> {
    if (!this.iapClient) {
      Logger.error('[PayService] IAP Client 未初始化.');
      return false;
    }

    try {
      // 步骤1: 向美寇服务器创建订单，获取唯一的商户订单号
      const merchantOrderNo = await this.createOrderOnServer(productId, amount);
      if (!merchantOrderNo) {
        throw new Error('创建商户订单失败');
      }

      // 步骤2: 准备支付参数
      const payParams: iap.PurchaseParams = {
        productId: productId, // 必须与华为后台配置一致
        productName: productName, // 商品名称
        amount: amount, // 金额（单位：分）
        merchantOrderNo: merchantOrderNo, // 关键：传入商户订单号，用于对账
        // 其他可选参数，如拓展信息等
      };

      // 步骤3: 调用IAP Kit，唤起支付
      const purchaseResult: PurchaseResultInfo = await this.iapClient.createPurchaseIntent(payParams);

      // 步骤4: 处理支付结果
      if (purchaseResult && purchaseResult.purchaseToken) {
        // 支付成功，获取到支付令牌(purchaseToken)
        const verifySuccess = await this.verifyPaymentOnServer(
          merchantOrderNo,
          purchaseResult.purchaseToken,
          purchaseResult.productId
        );

        if (verifySuccess) {
          // 服务器校验通过，完成交易
          await this.deliverProduct(productId, purchaseResult.purchaseToken);
          Logger.info(`[PayService] 支付成功！商品: ${productId}, 订单号: ${merchantOrderNo}`);
          return true;
        } else {
          Logger.error(`[PayService] 服务器支付凭证校验失败，订单: ${merchantOrderNo}`);
          // 可选择触发退款或告警
          return false;
        }
      } else {
        // 用户取消支付或其他失败
        Logger.warn(`[PayService] 支付未完成或取消. Code: ${purchaseResult?.returnCode}`);
        return false;
      }
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      Logger.error(`[PayService] 支付过程异常: Code=${err.code}, Message=${err.message}`);
      return false;
    }
  }

  // 在美寇商城服务器创建订单
  private async createOrderOnServer(productId: string, amount: number): Promise<string | null> {
    const httpRequest = http.createHttp();
    try {
      const requestData = {
        productId: productId,
        amount: amount,
        timestamp: new Date().getTime()
      };
      const response = await httpRequest.request(this.serverCreateOrderUrl, {
        method: http.RequestMethod.POST,
        header: { 'Content-Type': 'application/json' },
        extraData: JSON.stringify(requestData)
      });

      if (response.responseCode === 200) {
        const result = JSON.parse(response.result as string);
        if (result.code === 0 && result.data?.orderNo) {
          return result.data.orderNo; // 返回服务器生成的订单号
        }
      }
      return null;
    } catch (error) {
      Logger.error(`[PayService] 创建服务器订单失败: ${error}`);
      return null;
    } finally {
      httpRequest.destroy();
    }
  }

  // 向美寇服务器提交支付凭证进行校验（防伪造）
  private async verifyPaymentOnServer(
    orderNo: string,
    purchaseToken: string,
    productId: string
  ): Promise<boolean> {
    const httpRequest = http.createHttp();
    try {
      const verifyData = {
        orderNo: orderNo,
        purchaseToken: purchaseToken,
        productId: productId
      };
      const response = await httpRequest.request(this.serverVerifyPayUrl, {
        method: http.RequestMethod.POST,
        header: { 'Content-Type': 'application/json' },
        extraData: JSON.stringify(verifyData)
      });

      if (response.responseCode === 200) {
        const result = JSON.parse(response.result as string);
        return result.code === 0 && result.data?.isValid === true;
      }
      return false;
    } catch (error) {
      Logger.error(`[PayService] 校验支付凭证失败: ${error}`);
      return false;
    } finally {
      httpRequest.destroy();
    }
  }

  // 发货或提供虚拟商品
  private async deliverProduct(productId: string, purchaseToken: string): Promise<void> {
    // 根据productId更新用户权益，例如开通VIP、增加金币等。
    // 对于非消耗型商品，需记录发放状态，防止重复发货。
    Logger.info(`[PayService] 向用户发放商品: ${productId}`);
    // 实际业务中，这里会调用用户服务或订单服务更新状态
  }

  // 查询非消耗型商品（如会员）的拥有状态
  async queryOwnedPurchases(): Promise<OwnedPurchase[]> {
    try {
      if (this.iapClient) {
        const ownedPurchases: OwnedPurchase[] = await this.iapClient.queryOwnedPurchases();
        return ownedPurchases;
      }
    } catch (error) {
      Logger.error(`[PayService] 查询已拥有商品失败: ${error}`);
    }
    return [];
  }
}

3.3 UI层调用示例 (ProductPage.ets)

import { PayService } from '../services/PayService';
import { Prompt } from '@ohos.prompt';

@Entry
@Component
struct ProductPage {
  private productId: string = 'vip_monthly';
  private productName: string = '美寇商城月度VIP会员';
  private amount: number = 2500; // 单位：分，即25.00元
  private payService: PayService = PayService.getInstance();
  @State isLoading: boolean = false;

  build() {
    Column() {
      // ... 商品详情展示
      Button('立即开通')
        .width('90%')
        .height(50)
        .backgroundColor('#FF2D79')
        .fontColor(Color.White)
        .fontSize(18)
        .enabled(!this.isLoading)
        .onClick(() => {
          this.handlePurchase();
        })
      if (this.isLoading) {
        LoadingProgress().color('#FF2D79')
      }
    }
  }

  private async handlePurchase(): Promise<void> {
    this.isLoading = true;
    const success = await this.payService.purchaseProduct(this.productId, this.productName, this.amount);
    this.isLoading = false;
    if (success) {
      Prompt.showToast({ message: '开通成功！欢迎加入VIP！', duration: 3000 });
      // 跳转至成功页面或刷新用户状态
    } else {
      Prompt.showToast({ message: '支付未完成', duration: 3000 });
    }
  }
}

四、 效果对比与最佳实践

4.1 集成前后效果对比

4.2 关键实践与避坑指南

1. 双重校验原则：客户端支付成功后，必须由美寇商城服务器携带purchaseToken和商户订单号请求华为服务器接口（orders/v2/token/verify）进行最终校验，这是防止伪造支付请求、保障资金安全的铁律。
2. 商品类型区分：
   • 消耗型商品：如金币、钻石，支付后需调用consumeOwnedPurchase进行消耗，方可再次购买。
   • 非消耗型商品：如永久会员，查询queryOwnedPurchases判断是否拥有。
   • 订阅型商品：需处理自动续期和查询订阅状态。
3. 订单关联：调用createPurchaseIntent时务必传入merchantOrderNo，确保华为侧支付订单与商户业务订单一一对应，便于对账和问题排查。
4. 沙箱测试：上线前务必使用IAP Kit的沙箱环境（iap.Env.SANDBOX）和测试账号进行完整流程测试，避免直接操作真实资金。
5. 异常处理与恢复：网络中断、应用崩溃可能导致支付状态不一致。应用启动时应检查是否有未完成的订单，并实现可靠的订单状态恢复机制。

五、 总结与展望

美寇商城接入华为支付，是构建鸿蒙原生应用完整商业闭环的关键一步。通过采用官方标准的IAP Kit、清晰的分层架构以及安全的服务器端校验流程，我们不仅实现了安全便捷的支付功能，更使应用深度融入鸿蒙生态。

展望未来，基于此支付基础，可进一步探索：

• 跨端支付体验：利用HarmonyOS分布式能力，实现手机下单、平板或智慧屏便捷支付的场景。
• 支付与卡片联动：将VIP状态、优惠券信息通过服务卡片展示在桌面，用户点击卡片可直接触发支付或续费。
• 智慧营销：结合华为分析服务，基于支付行为进行精准的用户分层与运营。

支付不仅是交易的结束，更是用户服务的开始。在HarmonyOS全场景生态下，安全、流畅的支付体验将成为美寇商城提升用户忠诚度、挖掘增长潜力的强大引擎。