跳到主要内容

数字人民币支付场景

  1. 用户手机端rom版本过低可能导致应用闪退，建议开发者对开放接口抛出的异常错误进行捕获并进行处理。
  2. 华为钱包最低版本要求为 1.0.8.305。

场景介绍​

从5.0.1(13)版本开始，新增支持数字人民币支付场景。

例如用户需要通过数字钱包充值话费，此时用户可打开商户APP应用，选好充值金额发起支付，商户通过接入数字人民币支付服务，拉起数字人民币收银台完成订单支付。

支持商户模型：运营机构或受理服务机构入网的商户

数字人民币收银台展示：

接入流程​

数字人民币支付接入流程如下：

步骤说明
开发准备请先完成开发准备后再进行下面的开发接入。 - 数字人民币接入准备
接入数字人民币支付根据数字人民币支付场景开发步骤完成接入。

业务流程​

开发者接入数字人民币支付服务，可以快速实现应用的数字人民币支付能力。

  1. 商户客户端请求商户服务器创建商品订单。
  2. 商户服务器按照商户模式（运营机构商户或受理服务机构商户）调用运营机构或受理服务机构提供的下单接口到数字人民币服务端下单，接口详情请参照商户合作的运营机构或受理服务机构提供的开发指引。
  3. 数字人民币服务端返回订单加密信息。
  4. 商户服务端组建订单信息参数orderInfo返回给商户客户端。
  5. 商户客户端调用requestEcnyPayment接口拉起Payment Kit客户端数字人民币收银台。
  6. Payment Kit客户端展示数字人民币支付收银台。
  7. 用户通过收银台选择数字人民币钱包完成支付，Payment Kit客户端请求数字人民币服务端处理支付。
  8. 数字人民币服务端成功受理支付订单并处理支付。
  9. 数字人民币服务端将支付结果返回给Payment Kit客户端。
  10. Payment Kit客户端展示支付结果页。
  11. 用户关闭支付结果页后Payment Kit客户端会返回支付状态给商户客户端。
  12. 支付处理完成后，数字人民币服务端会异步通知支付结果信息给商户服务端。

接口说明​

接口返回值返回形式为Promise。具体API说明详见接口文档。

接口名描述
requestEcnyPayment(context:common.Context, orderInfo: EcnyOrderInfo): Promise<EcnyPayResult>;拉起数字人民币收银台。

开发步骤​

获取开发指引​

拨打数字人民币客服热线（956196）获取运营机构或受理服务机构提供的开发指引。

预下单（服务器开发）​

开发者需要按照运营机构或受理服务机构提供的开发指引进行开发。

拉起数字人民币收银台（端侧开发）​

商户客户端使用orderInfo作为参数调用requestEcnyPayment接口拉起数字人民币收银台。

当接口通过.then()方法返回时，则表示当前订单支付成功，通过.catch()方法返回表示订单支付失败。

当此次请求有异常时，可通过error.code获取错误码，错误码相关信息请参见错误码。

示例代码如下：

import { BusinessError } from '@kit.BasicServicesKit';
import { ecnyPaymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';
 
@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestEcnyPaymentPromise() {
    // use your own orderInfo
    const orderInfo: ecnyPaymentService.EcnyOrderInfo = {
      merchantAppId: "***",
      merchantNo: "***",
      acqAgtInstnId: "***",
      creditorInstitutionId: "***",
      encryptedKey: "***",
      encryptedInfo: "***",
      encryptionSN: "***",
      extraInfo: "***",
      lastWalletId: "***"
    };
    ecnyPaymentService.requestEcnyPayment(this.context, orderInfo)
      .then((result: ecnyPaymentService.EcnyPayResult) => {
        // pay success
        console.info(`succeeded in paying, result.orderNo: ${result.orderNo}, result.extraInfo: ${result.extraInfo}`);
      })
      .catch((error: BusinessError) => {
        // failed to pay
        console.error(`failed to pay, error.code: ${error.code}, error.message: ${error.message}`);
      });
  }
 
  build() {
    Column() {
      Button('requestEcnyPaymentPromise')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestEcnyPaymentPromise();
        })
      }
    .width('100%')
    .height('100%')
  }
}

  • 如果初次使用数字人民币收银台，系统会自动通过拉起数字人民币元服务，完成授权登录。
  • 支付成功，不建议以客户端返回作为用户的支付结果，需以服务器接收到的结果通知或者查询API返回为准。

支付结果回调通知（服务器开发）​

开发者需要按照运营机构或受理服务机构提供的开发指引进行开发。