HarmonyOS 鸿蒙Next 华为支付服务（Payment Kit）的探索之旅 简化交易，提升体验

在数字支付领域，华为支付服务（Payment Kit）简化了交易过程，还为用户带来了前所未有的便捷体验。今天，我们一起学习华为支付服务的基本概念、能力开发的前置条件以及基本流程。

       1. 华为支付服务是什么？

华为支付服务（Payment Kit）是HarmonyOS系统下的一种支付解决方案，它利用系统级接口，提供了一系列强大的支付、营销和运营功能。这意味着开发者可以无缝集成这些能力到他们的应用或元服务中，从而让用户能够轻松购买实体商品或服务，并立即看到支付结果。

       2. 华为支付服务能力开发的前置条件？

要成功接入华为支付服务，开发者需要满足一些基础条件。首先，必须拥有一个有效的HarmonyOS开发者账号。其次，根据业务需求选择合适的接入模式：商户模式、平台类商户模式或服务商模式。每种模式都有其特定的要求和优势，因此选择合适的模式对于实现最佳集成至关重要。

        3. 华为支付服务能力的基本流程？

一旦选择了合适的接入模式并满足了所有前置条件，开发者就可以开始集成华为支付服务了。这个过程通常包括以下几个步骤：注册和配置支付服务账号、集成SDK、设置支付参数、测试和验证支付流程。每一步都旨在确保支付过程的安全性、可靠性和用户友好性。

收银台服务展示

图 3-8-1 收银台业务流程

3.8.4华为支付服务开发的前置条件

为了使用AppGallery Connect（简称AGC），我们需要首先在AGC平台上创建一个项目。同时，我们必须在本地准备一个相应的项目工程。例如，我们这里创建了一个名为Chapter0806的工程，旨在帮助开发者掌握华为支付服务的功能。重要的是，确保工程的包名与在AppGallery Connect创建应用时使用的包名完全相同。

AGC（AppGallery Connect）配置流程

特别要注意的是：Bundle name（包名）需要与AGC创建应用时的应用包名一致，这里以com.nutpi.chapter0806为例。

接下来，我将回忆一下如何在DevEco Studio中创建本地工程：

本地工程创建流程

方式一：当DevEco Studio没有打开任何工程时，你可以在欢迎页选择“Create Project”来打开新工程创建向导。

方式二：如果已经打开了一个工程，你可以通过菜单栏选择“File > New > Create Project”来打开新工程创建向导。

注意：在创建新工程时，确保Bundle name（包名）与AGC创建应用时的应用包名保持一致。

按照这些步骤，你可以顺利地在本地创建一个新的项目工程，并确保它的配置与AGC平台上的项目设置相匹配，从而顺利地进行华为支付服务的开发和集成。

图 3-8-2 创建项目

AGC（AppGallery Connect）创建流程

步骤一：项目创建

1. 登录到AppGallery Connect（简称AGC）平台。
2. 点击“我的项目”选项，进入项目列表页面。
3. 在项目列表页面中，点击“添加项目”按钮。
4. 输入你想要的项目名称，然后点击“创建并继续”以进入下一步。

步骤二：添加应用

1. 项目创建完成之后，进入项目设置页面。
2. 在项目设置页面中，点击“添加应用”按钮。
3. 在“添加应用”页面中，你需要设置相关的应用参数。
4. 确认所填写的应用包名与你在DevEco Studio中创建的HarmonyOS应用工程的Bundle name一致，例如：com.nutpi.chapter0806。
5. 在选择应用分类时，请选择“应用”。
6. 完成上述步骤后，点击“确认”以完成应用的添加。

注意：确保应用包名与你的HarmonyOS应用工程的Bundle name完全一致，这是确保应用能够正确集成和运行的关键。

按照这些步骤，你可以顺利地在AGC上创建项目并添加应用，为接下来在HarmonyOS平台上开发和发布你的应用做好准备。

图 3-8-3 AGC 项目常规页面

图 3-8-4 AGC 应用创建页面

添加公钥指纹

当应用需要集成如Account Kit（华为账号服务）、Call Kit（通话服务）、Game Service Kit（游戏服务）、Health Service Kit（运动健康服务）、IAP Kit（应用内支付服务）、Live View Kit（实况窗服务）、Map Kit（地图服务）、Payment Kit（华为支付服务）和Push Kit（推送服务）等华为开放能力时，为了确保应用能够正常调试和运行，必须在开发者平台预先添加公钥指纹。

为何需要添加公钥指纹？

添加公钥指纹是为了验证开发者的身份，确保只有经过授权的开发者才能使用这些服务。这是一项安全措施，用以防止未授权的访问和确保应用与华为开放能力的无缝集成。

怎样添加公钥指纹

步骤一：申请应用证书（.cer）、Profile（.p7b）文件。具体操作参见调试HarmonyOS应用/元服务。

步骤二：添加公钥指纹。具体操作参见配置应用签名证书指纹。

步骤三：真机或模拟器需要在设置界面中登录华为实名认证的账号。

开通 Payment Kit

步骤一：登录AppGallery Connect平台，选择“我的项目”。

图 3-8-5 AGC 首页

步骤二：在项目列表中找到项目，在项目下的应用列表中选择需要开通Payment Kit的应用。

图 3-8-6 AGC 应用列表

步骤三：在左侧导航栏选择“盈利 > 华为支付服务（非虚拟类） > 立即开通”。

图 3-8-7 AGC 华为支付服务

步骤四：（如果已有商户号请忽略本步骤）点击“申请支付商户号”，详细介绍参考华为支付商户入网。申请商户号后，还需要为商户号申请绑定AppID，详细参见商户号绑定AppID。

商户号绑定AppID

在华为支付平台，商户的支付交易能力与其在AppGallery Connect中创建的应用的AppID紧密相关。商户必须将其商户号与相应的AppID绑定，才能顺利进行支付交易。这一过程对于确保交易的安全性和正确性至关重要。下面将介绍如何进行AppID的绑定以及相关的注意事项：

绑定AppID的步骤

1. 登录华为支付商户平台：首先，作为商户，你需要登录到华为支付商户平台。
2. 发起绑定申请：在平台内找到绑定AppID的选项，并发起绑定申请。如果商户号与AppID所关联的营业主体信息相同（即同主体），则此步骤通常无需华为支付的人工审核。
3. 异主体绑定：如果尝试将商户号与不同主体的AppID绑定（即异主体），则需要联系华为支付的产品侧进行沟通，申请绑定权限。在获得权限并经过华为支付人工审核后，应用管理员需要登录到AppGallery Connect网站完成对商户号的AppID绑定授权。
4. 绑定确认：完成上述步骤后，确认AppID与商户号的绑定关系已经成功建立。

注意事项

暂不支持的商户类型：请注意，平台子商户及特约商户目前无法自行发起绑定AppID的申请。

同主体与异主体：确认你的商户号与AppID是否属于同一营业主体。如果是，则绑定过程会更简单，否则需要更多的审核步骤。

安全性考虑：维护AppID的安全性是非常重要的，因为它与你的商户号直接相关联，并用于处理支付交易。

通过以上步骤，可以确保组织或个人的商户号与AppID正确绑定，从而在华为支付平台上顺利开展支付交易。正确的绑定不仅保证了交易的安全执行，也有助于提升用户体验和管理效率。

特定场景配置操作

在华为支付平台上，特定场景下的配置操作需要商户或服务商进行一些特别的设置和授权。以下是这些特定场景及其配置操作的步骤和注意事项：

接入非快捷支付能力

1. 联系产品侧开通：如果商户需要接入非快捷支付方式，如签约代扣，需提前联系华为支付的产品团队以开通相应的支付产品。这是因为某些支付方式可能需要额外的审核或配置。
2. 技术对接：在获得相应产品的接入权限后，商户可以根据华为支付提供的开发文档和API接口进行技术对接，确保支付方式能够正确集成到商户的系统中。

生成及下载对账单

1. 开启对账单接口：商户的管理员需要在“华为支付商户平台”中进入“功能设置”，找到“对账单接口获取开关”并开启它。这样做是为了允许系统自动生成对账单。
2. 对账单生成时间：开启对账单接口后，系统将从次日开始生成前一日的对账单。例如，如果3月10日开启了此功能，则3月11日会生成3月10日的对账单。
3. 下载对账单：对账单生成后，管理员可以在指定的目录下下载对账单文件，以便进行财务审计和记录保持。

特约商户退款授权操作

1. 申请API退款授权：对于服务商代表特约商户发起的退款场景，服务商需要在华为支付商户平台上申请API退款授权。这是为了确保退款请求是由有权限的实体发出的。
2. 完成授权操作：在获得授权后，服务商可以代表特约商户执行退款操作。这通常涉及到使用特定的API密钥或其他安全认证方法来确认退款请求的合法性。
3. 注意安全和合规性：在进行退款操作时，确保遵守所有相关的安全和合规性要求，以防止未授权的交易和保护消费者的资金安全。

通过遵循上述步骤和注意事项，商户和服务商可以在华为支付平台上有效地管理和执行特定场景下的支付、对账和退款操作。这些操作的正确配置是确保交易流程顺畅、安全和高效的关键。

图 3-8-8  AGC 商户平台页面

商户证书准备

商户证书是一份关键文件，由商户主动申请并包含商户号、公司名称及公钥信息。此证书必须以pem格式创建，同时支持RSA与SM2两种加密算法。商户需自行生成符合要求的公私密钥对，并将其上传至华为支付商户平台。

只有在商户将公钥证书成功提交至华为支付商户平台之后，才能获得一个证书ID，此ID用于HTTP请求头中鉴权信息PayMercAuth对象的authId字段。完成商户入网流程后，可在商户中心的“证书管理”部分，通过“上传商户证书”功能来获取“证书ID”。

图 3-8-9 已上传证书列表

商户证书使用说明

关于证书准备的内容，以下是商户私钥和华为支付证书的详细说明：

商户私钥

当商户自行生成或申请商户证书时，会同时生成一个商户私钥。这个私钥对于商户来说至关重要，因为它用于对API请求中的信息进行签名。商户必须确保私钥文件的安全，避免在任何公共场合暴露私钥，例如不应上传到公共平台如GitHub，也不应将其写入客户端代码中。商户私钥的安全保管是保障交易安全的关键步骤。

华为支付证书

华为支付证书是由华为支付平台提供的，其中包含了华为支付平台的标识和公钥信息。这个证书使用的是SM2加密算法。商户需要从华为支付商户平台下载该证书，它主要用于验证回调通知的信息。具体来说，华为支付证书中的公钥使商户能够对接收到的回调通知进行验签，从而确认通知的真实性和有效性。

商户在处理与华为支付相关的证书和私钥时，必须严格遵守安全规范，确保所有敏感信息的安全，以防止未授权访问和潜在的安全风险。正确的证书和私钥管理是确保交易安全、保护用户数据和维持系统完整性的基础。

图 3-8-10 商户证书使用流程

商户证书生成

商户在生成公钥证书后，需要手动将其上传到华为支付商户平台。这一步骤至关重要，因为公钥证书将用于Payment Kit服务器对支付请求的签名进行验证。

商户证书要求

商户证书的生成需要满足以下具体要求：

• 文件格式：商户上传的公钥证书必须为“*.pem”格式，以确保与华为支付平台的兼容性。
• 密钥规格：在生成RSA公私钥对时，密钥长度必须至少为3072位，以确保安全性。同时，密钥格式应为PKCS#8。

使用JavaScript库生成密钥

商户可以使用JavaScript的一个库在线下环境中生成所需的密钥。以下是具体的操作步骤：

1. 确保已经配置好Node.js执行环境。
2. 使用文本编辑器创建一个新的文件，并将提供的代码复制到该文件中。保存文件并命名为“generateKeyPair.js”。
3. 打开命令行工具，导航到文件所在的目录，并执行命令 node generateKeyPair.js。
4. 执行完毕后，从命令行工具的输出中复制生成的公私钥，并将其妥善保存以备后续使用。

通过以上步骤，商户可以正确地生成和准备所需的证书和密钥，以确保与华为支付平台的无缝对接和交易的安全处理。

商户证书上传与下载

关于上传商户证书

为确保交易安全及系统对接的顺利进行，请登录华为支付商户平台并前往“证书管理 > 上传商户证书”模块，按照指定的生成方式及要求，上传商户证书公钥。这一步骤非常关键，因为它涉及到后续支付请求的验证过程。

图 3-8-11 命令行界面

下载华为支付证书

在完成商户证书公钥的上传后，您还需要通过华为支付商户平台的“华为支付证书”模块下载华为支付证书。此证书对于验证华为支付向您的业务系统发送的各种信息至关重要，包括但不限于支付结果通知等。确保在您的系统中正确配置和使用该证书，以保障交易信息的准确性和安全性。

图 3-8-12 华为支付平台模块页面

端侧应用配置

在HarmonyOS应用/元服务“entry/src/main/module.json5”文件中module的metadata节点下增加client_id和app_id属性配置。

图 3-8-13 AGC 应用信息

图 3-8-14 项目模块增加client_id

华为支付服务的基本流程

单次支付业务流程

关于单次支付业务流程，开发者可以通过接入Payment Kit的单次支付功能，轻松且高效地为应用添加支付功能。以下是单次支付的具体业务流程：

1. 创建商品订单：商户客户端向商户服务器发起请求，以创建商品订单。这一步骤是支付流程的起点，确保了购买请求的有效性和准确性。
2. 获取预下单号：商户服务器根据商户的业务模型，调用Payment Kit提供的API（直连商户预下单或平台类商户/服务商预下单接口），以获取预下单号（prepayId）。此预下单号是后续支付流程中的关键标识。
3. 组建订单字符串：商户服务器将包括预下单号在内的订单信息组装成订单字符串（orderStr），并将其返回给商户客户端。这一步骤为客户端提供了必要的支付信息。
4. 调起Payment Kit客户端：商户客户端通过调用requestPayment接口，唤起Payment Kit客户端收银台。此时，用户可以看到支付页面，进行支付操作。
5. 完成支付操作：用户在Payment Kit客户端收银台完成支付操作后，Payment Kit客户端会接收到支付结果信息。这标志着用户已完成支付动作。
6. 展示支付结果：Payment Kit客户端会展示支付结果页面，用户可以查看支付状态。当用户关闭支付结果页面后，Payment Kit客户端会将支付状态返回给商户客户端，以便其进行后续处理。
7. 支付结果回调：支付完成后，Payment Kit服务器会通过回调接口将支付结果信息发送给商户服务器。这一步骤确保了商户服务器能够实时获取支付状态。
8. 验证支付结果：商户服务器收到支付结果回调响应后，需使用SM2验签方式对支付结果进行验证。这一步骤是确保支付结果未被篡改、是安全可靠的。

图 3-8-15 华为支付流程

单次支付接口说明

• requestPayment(context: common.UIAbilityContext, orderStr: string): Promise<void>
• requestPayment(context: common.UIAbilityContext, orderStr: string, callback: AsyncCallback<void>): void

接口服务说明：用于拉起Payment Kit支付收银台。

单次支付开发步骤

在开发华为支付的单次支付功能时，开发者可以按照以下步骤来确保支付流程的正确性和安全性：

步骤一：预下单（服务器开发）

1. 获取预支付ID：开发者根据商户的业务模型，通过调用直连商户预下单或平台类商户/服务商预下单接口，获取预支付ID（prepayId）。此ID是后续支付流程的关键标识。
2. 签名请求：为保证支付订单的安全性和可靠性，开发者需要对请求体（body）和请求头（PayMercAuth对象）内的参数进行排序、拼接并进行签名。具体的排序、拼接和签名过程可以参考相关的示例代码。
3. 构建订单字符串：商户服务器需构建包含必要支付信息（如预支付ID等）的订单字符串（orderStr），并对该字符串进行签名，然后将其返回给客户端。

图 3-8-16 下单无参接口代码参考

图 3-8-17 下单带参接口代码参考

步骤二：拉起华为支付收银台（端侧开发）

1. 调用支付接口：在客户端，开发者调用requestPayment接口来唤起Payment Kit支付收银台，让用户进行支付操作。
2. 处理支付结果：接口调用成功后，会通过then()返回，表明当前订单支付成功。如果请求出现异常，可以通过error.code获取错误码以便进行问题定位和处理。

图 3-8-18 支付结果代码

步骤三：支付结果回调通知（服务器开发）

1. 接收支付信息：支付成功后，Payment Kit服务器会调用开发者提供的回调接口，将支付信息返回给开发者的服务器。详细的回调信息格式请参考直连商户支付结果回调通知或平台类商户/服务商支付结果回调通知的相关文档。
2. 验证支付信息：为确保接收到的支付信息的合法性，商户服务器必须使用SM2算法对返回的支付信息进行验签。验签过程中，需要直接使用通知的完整内容进行验签，且在验签前对返回数据进行排序拼接，确保sign字段（签名值）被排除在待验签内容之外。验签所需的公钥应从华为支付证书中获取。

图 3-8-19 请求带参包

完成以上步骤后，我们可以继续调用其他API接口，如查询支付订单、申请退款、查询退款订单等，以完成订单的其他相关操作。实现完整的支付流程同时，还能确保整个流程的安全性和可靠性。