鸿蒙开发-HMS Kit能力集(地图服务、华为支付服务)
地图服务
Map Kit（地图服务）是鸿蒙生态下的一个地图服务，为开发者提供强大而便捷的地图能力，助力全球开发者实现个性化地图呈现、地图搜索和路线规划等功能，轻松完成地图构建工作。
Map Kit提供了千万级别的 Poi（Point of Interest，兴趣点）。在地图表达中，一个 Poi 可代表一家商铺、一栋办公楼、一处景点等等。
Map Kit在Poi和路网信息展示方面，根据Poi属性信息及区域路网差异，在不同层级比例尺条件下，为用户展示更合适的Poi和路网信息。手势交互方面，提供了包括缩放、旋转、移动、倾斜等流畅的交互体验。
AGC控制台创建应用
步骤一：登录AppGallery Connect（简称AGC），点击“我的项目”，在项目中点击“添加项目”，输入项目名称后，点击“创建并继续”。
步骤二：项目创建完成后， “添加应用”.
注：应用包名需与DevEco Studio 创建HarmonyOS应用工程的Bundle name一致。
创建HarmonyOS工程
新工程包名需与AppGallery Connect创建应用时一直。
注：Bundle name需与AGC创建应用时应用包名一致
Client_id设置
新工程的entry模块的module.json5配置的module下，加入AGC应用的client_id分支设置
"metadata": [
{
"name": "client_id",
"value": "111403049"
//配置为获取的Client ID
}
]
添加公钥指纹
调试Map Kit（华为账号）必须
- 使用一台登录了华为账号的真机
- 对工程自动签名，产生调试证书
- 在AGC上对应的项目中，添加公钥指纹
开通地图服务
应用的“API管理”中搜索map，开启“地图服务”
地图呈现
MapComponent是地图组件，用于在您的页面中放置地图。
MapComponentController是地图组件的主要功能入口类，用来操作地图，与地图有关的所有方法从此处接入。
它所承载的工作包括：地图类型切换（如标准地图、空地图）、改变地图状态（中心点坐标和缩放级别）、添加点标记（Marker）、绘制几何图形(MapPolyline、MapPolygon、MapCircle)、各类事件监听等。
MapComponent接口说明
我的位置权限
启用“我的位置”之前，您需要确保您的应用可以获取用户定位。获取用户定位有两种方式：
方式一：申请ohos.permission.LOCATION和ohos.permission.APPROXIMATELY_LOCATION权限，需在module.json5配置文件中声明所需要的权限
"requestPermissions": [
{
"name": "ohos.permission.LOCATION",
"reason": "$string:location_permission",
"usedScene": {
"abilities": [
"MainAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.LOCATION_IN_BACKGROUND",
"reason": "$string:background_location_permission",
"usedScene": {
"abilities": [
"MainAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:fuzzy_location_permission",
"usedScene": {
"abilities": [
"MainAbility"
],
"when": "inuse"
}
}
]
请求权限代码
import { abilityAccessCtrl, bundleManager, common, PermissionRequestResult, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
华为支付服务
Payment Kit（华为支付服务）提提供了方便、安全和快捷的支付方式，将强大的支付、营销、运营等能力通过HarmonyOS系统级接口形式开放给广大开发者，集成便捷且快速。用户可在开发者的应用/元服务内通过支付完成实体商品或服务的购买并展示支付结果。
华为支付功能由花瓣支付（深圳）有限公司提供，打造更安全、更便捷的HarmonyOS系统支付体验，助力开发者的业务增长。
Payment Kit当前提供三种接入方式：商户、平台类商户、服务商，开发者需要根据实际业务模式选择适用的合作身份。
华为支付接入分类
- 华为支付接入分类
开发者可以选择直连商户模式，直接与华为支付对接，使用华为支付服务的经营主体。该模式下，我们提供支付产品及签约代扣产品，支持您的多种载体，包括HarmonyOS应用和元服务。
- 服务商
开发者可以选择服务商模式，作为华为支付商户与华为支付之间的连接者，为商户提供开户申请、支付接入、技术开发等综合解决方案机构，您需要在中国支付清算协会备案。该模式下，我们提供支付产品，支持您的多种载体，包括HarmonyOS应用和元服务。
- 平台类商户
开发者可以选择服务商模式，作为华为支付商户与华为支付之间的连接者，为商户提供开户申请、支付接入、技术开发等综合解决方案机构，您需要在中国支付清算协会备案。该模式下，我们提供支付产品，支持您的多种载体，包括HarmonyOS应用和元服务。
华为支付服务场景
- 商城购物场景
用户在商户App选购完不同的商品后，可以直接在商户App应用内完成下单和支付。
- 会员包月场景
用户在商户App应用/元服务开通会员，在支付流程中，同时完成支付和签约，待签约生效后，商家可以按照协议中的时间直接发起免密代扣请求完成扣款续费，无需用户每个月都进行开通会员操作。
- 会员续费场景
用户在商户App应用/元服务中完成签约关系后，会员到期后商户系统可以直接发起免密代扣请求完成扣款续费，无需用户进入收银台并且输入支付密码。
华为支付服务功能
- 移动支付
商户可在移动端App中集成华为支付功能，轻松实现线上收款，支持银行卡、余额等支付工具。
- 元服务支付
商户可在元服务应用中集成华为支付功能，轻松实现线上收款，支持银行卡、余额等支付工具。
- 签约代扣
针对商户需要用户周期付款场景下推出的功能，与用户签订协议后，商户可按照约定的代扣规则发起扣款。
AGC控制台创建应用
步骤一：登录AppGallery Connect（简称AGC），点击“我的项目”，在项目中点击“添加项目”，输入项目名称后，点击“创建并继续”。
步骤二：项目创建完成后，点击项目设置页面“添加应用”按钮，在“添加应用”页面中设置参数后，点击“确认”。
注：应用包名需与DevEco Studio 创建HarmonyOS应用工程的Bundle name一致，均为com.nutpi.chapter0308，且应用分类选择“游戏”。
添加公钥指纹
调试Payment Kit（华为支付）必须
- 使用一台登录了华为账号的真机
- 对工程自动签名，产生调试证书
- 在AGC上对应的项目中，添加公钥指纹
开通Payment Kit
步骤一：登录AppGallery Connect平台，选择“我的项目”。
步骤二：在项目列表中找到项目，在项目下的应用列表中选择需要开通Payment Kit的应用。
步骤三：在左侧导航栏选择“盈利 > 华为支付服务（非虚拟类） > 立即开通”。
步骤四：（如果已有商户号请忽略本步骤）点击“申请支付商户号”，详细介绍参考华为支付商户入网。申请商户号后，还需要为商户号申请绑定AppID，详细参见商户号绑定AppID。
商户号绑定AppID
绑定AppID说明
商户后续支付交易依赖于AppGallery Connect中创建应用生成的AppID与商户号的关联关系，因此在华为支付商户入网成功后，需要在华为支付商户平台将商户号与AppID进行绑定才可发起交易。
暂不支持平台子商户及特约商户发起绑定AppID申请。
商户发起绑定AppID申请，同主体（商户号、AppID所关联的营业主体信息）时无需华为支付人工审核。异主体绑定需要商户联系产品侧沟通，申请绑定权限后才可发起绑定以及需要华为支付人工审核后，应用管理员登录AppGallery Connect网站才能对商户号绑定AppID进行授权。
AppID主体与特约商户一致或者与服务商一致，则认为同主体。
特定场景配置操作
接入非快捷支付（即非单次支付）能力，需商户提前联系产品侧开通对应产品（如签约代扣）。
如需要生成及下载对账单，需管理员先在“华为支付商户平台>功能设置”中开启“对账单接口获取开关”，开启后次日开始生成前一日的账单。
涉及服务商户代特约商户发起退款场景，需要服务商在华为支付商户平台上申请API退款授权完成特约商户退款授权操作。
证书准备
商户证书是指由商户申请的，包含商户的商户号、公司名称、公钥信息的证书。该证书文件要求为pem格式，支持RSA和SM2两种算法。商户可以自行生成公私秘钥证书，上传至华为支付商户平台。
商户将公钥证书提交到华为支付商户平台后才能获得证书ID，证书ID为请求HTTP请求头鉴权信息PayMercAuth对象中的authId。商户入网完成后，可以在：“商户中心”->“证书管理”->“上传商户证书”->“证书ID”处获取。
商户私钥
商户自行生成或申请商户证书时，会配套生成商户私钥。请妥善保管好商户私钥文件。
商户请求签名使用商户私钥，请妥善保管好商户私钥文件，不要把私钥文件暴露在公共场合，如上传到Github，写在客户端代码等。
商户私钥用于商户对API请求中的信息进行签名。
华为支付证书
华为支付证书是指由华为支付提供的，包含华为支付平台标识、公钥信息的证书。该证书算法为SM2。
商户请通过华为支付商户平台下载华为支付证书。
华为支付证书中的公钥用于商户对回调通知中的信息进行验签。
商户证书生成
公钥证书生成后须商户手动上传到平台，用于Payment Kit服务器对支付请求验证签名。
商户证书需要满足如下要求：
后缀要求：华为支付商户平台接收的公钥证书格式为“*.pem”。
格式要求：生成RSA公私钥时，密钥长度要求不小于3072，密钥格式为PKCS#8。
使用JavaScript的库线下生成
配置好node执行环境并使用文本编辑器新建文件，拷贝以下代码到文件中并保存命名为“generateKeyPair.js”。
打开命令行工具，执行node generateKeyPair.js命令。
从结果中拷贝生成的公私钥并保存。结果如右图所示：
商户证书上传与下载
上传商户证书
请登录华为支付商户平台，在“证书管理 >上传商户证书”模块进行商户证书公钥上传（生成方式及上传要求请参见商户证书生成）。
待上传公钥信息示例：
下载华为支付证书
通过“华为支付证书”模块进行华为支付证书下载，该证书用于校验华为支付给商户业务系统发送的信息，如支付结果信息等。
端侧应用配置
在HarmonyOS应用/元服务“entry/src/main/module.json5”文件中module的metadata节点下增加client_id和app_id属性配置。
云侧服务准备
华为支付服务提供了支付系统相关的一系列API接口。为减小API接口的接入工作量，华为支付服务提供了java版本对应的maven依赖用于云侧服务对接。
开发者可通过Maven集成来完成服务器开发环境的构建，以此来快速使用华为支付提供的API接口。
可下载示例代码支付-华为支付服务-服务端用以快速完成商户服务器接入。
单次支付业务流程
开发者通过接入Payment Kit单次支付，可以简便快捷的实现应用的支付能力。
- 商户客户端请求商户服务器创建商品订单。
- 商户服务器按照商户模型调用Payment Kit提供的直连商户预下单或平台类商户/服务商预下单接口获取预下单号（prepayId），然后组建orderStr返回给客户端。
- 商户客户端调用requestPayment接口调起Payment Kit客户端收银台。
- 用户在Payment Kit客户端收银台完成支付操作后，Payment Kit客户端会收到支付结果信息。
- Payment Kit客户端展示支付结果页，用户关闭支付结果页
- Payment Kit客户端会返回支付状态给商户客户端。
- 支付完成后，Payment Kit服务器会调用回调接口返回支付结果信息给商户服务器。
- 商户服务器收到支付结果回调响应后，使用SM2验签方式对支付结果进行验签。
单次支付开发步骤
步骤一：预下单（服务器开发）
开发者按照商户模型调用直连商户预下单或平台类商户/服务商预下单接口获取预支付ID（prepayId）。
为保证支付订单的安全性和可靠性需要对请求body和请求头PayMercAuth对象内的入参排序拼接进行签名。请参考排序拼接和签名示例代码。
构建orderStr。
商户服务器需要将客户端支付接口入参orderStr签名后返回给客户端。
步骤二：拉起华为支付收银台（端侧开发）
调用requestPayment接口拉起Payment Kit支付收银台。
当接口通过then()返回时，则表示当前订单支付成功。
当此次请求有异常时，可通过error.code获取错误码
步骤三：支付结果回调通知（服务器开发）
支付成功后Payment Kit服务器会调用开发者提供的回调接口，将支付信息返回给开发者的服务器，回调详细信息按商户模式请参见直连商户支付结果回调通知或平台类商户/服务商支付结果回调通知。
为保证信息合法性，商户服务器需要对返回的支付信息进行SM2验签，验签注意事项：
需直接使用通知的完整内容进行验签。
验签前需要对返回数据进行排序拼接，sign字段是签名值，排序拼接后的待验签内容需要排除sign字段。
验签公钥使用华为支付证书。
右侧为支付结果回调通知请求示例：
当开发者完成上述能力之后，可以调用诸如查询支付订单、申请退款、查询退款订单等API接口完成订单其他相关操作。
