华为支付
目 录
一、概述
Payment Kit（鸿蒙支付服务）是华为为开发者提供的支付解决方案，支持在商户应用、元服务中快速集成安全、便捷的支付功能。通过拉起华为支付收银台，用户可完成实体商品或服务的购买，商户可同步获取支付结果并完成订单闭环。
二、商户模型
在接入华为支付服务前，请根据您的实际业务模式选择合适的合作身份。华为支付目前提供以下三种接入方式：商户、平台类商户、服务商。
商户(直连商户模式): 直接与华为支付对接，使用华为支付服务的经营主体。
平台类商户： 面向为商品交易或服务提供线上撮合与管理平台的商户，华为支付为其提供的支付与结算解决方案。
服务商： 作为华为支付与商户之间的连接桥梁，根据服务内容主要分为两类：技术服务商、收单外包服务机构。
三、支付能力
四、开发准备
四.1. 商户入网与获取商户号
华为支付当前仅支持商户接入，在开发前需要先完成华为支付商户入网。商户入网后会分配对应的商户号，商户号作为开放API接口请求的必要入参。
四.2. 开通支付服务
1. 登录AppGallery Connect网站，选择“开发与服务”。
2. 在项目列表中找到项目（如未创建项目可点击添加项目先完成项目创建），在项目下的应用列表中选择需要开通Payment Kit的应用。
3. 在左侧导航栏选择“盈利 > 鸿蒙支付服务 > 支付服务（非虚拟类）> 立即开通”。
四.3. 商户号绑定AppID（直连商户、平台类商户）
1. 登录华为支付商户平台进入“商户中心 > 产品功能 > AppID管理 > 新增关联AppID”。
2. 申请绑定AppID后，应用管理员登录AppGallery Connect网站选择对应的项目后，在左侧导航栏选择“盈利 > 鸿蒙支付服务 > 支付服务（非虚拟类） > 待关联商户号”选择对应的商户点击“授权”。
四.4. 准备证书
开发者接入华为支付开放API接口，需要通过证书来对请求内容及响应内容做签名和验证签名，以保证请求的安全性和可靠性。需准备证书：商户证书、华为支付证书（公钥）。
四.4.1. 商户证书
商户证书是包含商户公钥和私钥信息的证书。由商户主动申请并包含商户号、公司名称及公钥信息。此证书必须以pem格式创建，同时支持RSA与SM2两种加密算法。商户需自行生成符合要求的公私密钥对，并将其上传至华为支付商户平台。只有在商户将公钥证书成功提交至华为支付商户平台之后，才能获得一个证书ID，此ID用于HTTP请求头中鉴权信息PayMercAuth对象的authId字段。完成商户入网流程后，可在商户中心的“证书管理”部分，通过“上传商户证书”功能来获取“证书ID”。
四.4.2. 华为支付证书
华为支付证书是华为支付平台提供的凭证，含平台标识与公钥信息，采用 SM2 加密算法。商户需从华为支付商户平台下载，该证书用于校验华为支付给商户业务系统发送的信息，如支付结果信息等。
下载华为支付证书：
登录华为支付商户平台后，通过“商户中心 > 证书管理 > 华为支付证书”页签进行华为支付证书下载。
四.5. 端侧应用配置
配置bundleName:
{
"app": {
*// bundleName需要与开发者在AppGallery Connect中创建应用时的包名保持一致*
"bundleName": "com.huawei.******.******.demo",
*// ...*
}
}
配置应用属性 :
“entry/src/main/module.json5”文件中module的metadata节点下增加client_id和app_id属性配置。
{
"module": {
*// ...*
"metadata": [
{
"name": "app_id",
"value": "***"
},
{
"name": "client_id",
"value": "***"
}
]
}
}
五、华为支付开发
五.1. 单次支付业务流程
1. 创建商品订单： 商户客户端向商户服务器发起请求，创建商品订单。
2. 获取预支付ID： 商户服务器调用Payment Kit预下单接口，获取预支付ID（prepayId）。
3. 组建订单字符串： 商户服务端组建订单信息参数orderStr签名后返回给商户客户端。
4. 拉起支付收银台 ： 商户客户端调用requestPayment接口，拉起Payment Kit支付收银台。
5. 完成支付操作： 用户在收银台完成支付，Payment Kit 客户端展示结果。
6. 支付结果回调： 支付完成后，Payment Kit服务器会通过回调接口将支付结果信息发送给商户服务器。
7. 验证支付结果： 商户服务器收到支付结果回调响应后，需使用SM2验签方式对支付结果进行验证。
五.2. 单次支付接口说明
requestPayment(context: common.UIAbilityContext, orderStr: string): Promise
说明： 该方法提供基础支付、支付并签约等功能，调用方法前请确保网络已连接，调用该方法后会拉起Payment Kit收银台，支付完成后使用Promise异步返回。
requestPayment(context: common.UIAbilityContext, orderStr: string, callback: AsyncCallback): void
说明： 该方法提供基础支付、支付并签约等功能，调用该方法前请确保网络已连接，调用该方法后会拉起Payment Kit收银台，支付完成后通过AsyncCallback回调结果。
五.3. 单次支付开发步骤
五.3.1. 预下单（服务器开发）
获取预支付ID ： 开发者根据商户的业务模型，通过调用直连商户预下单、平台类商户或服务商的预下单接口，获取预支付ID（prepayId）。
签名请求 ： 为保证支付订单的安全性和可靠性，开发者需要对请求体（body）和请求头（PayMercAuth对象）内的参数进行排序、拼接并进行签名。
构建订单字符串 ： 商户服务器需构建包含必要支付信息（如预支付ID等）的订单字符串（orderStr），并对该字符串进行签名，然后将其返回给客户端。
五.3.2. 拉起华为支付收银台（端侧开发）
调用支付接口 ： 在客户端，开发者调用requestPayment接口来唤起Payment Kit支付收银台，让用户进行支付操作。
处理支付结果 ： 接口调用成功后，会通过then()返回，表明当前订单支付成功。如果请求出现异常，可以通过error.code获取错误码以便进行问题定位和处理。（支付成功，不建议以客户端返回作为用户的支付结果，需以服务器接收到的结果通知或者查询API返回为准。）
import { BusinessError } from '@kit.BasicServicesKit';
import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';
@Entry
@Component
struct Index {
context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
requestPaymentPromise() {
const orderStr = '{"app\_id":"***","merc\_no":"***","prepay\_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"\*\***","auth\_id":"**\*"}';
paymentService.requestPayment(this.context, orderStr)
.then(() => {
console.info('succeeded in paying');
})
.catch((error: BusinessError) => {
console.error(`failed to pay, error.code: ${error.code}, error.message: ${error.message}`);
});
}
build() {
Column() {
Button('requestPaymentPromise')
.type(ButtonType.Capsule)
.width('50%')
.margin(20)
.onClick(() => {
this.requestPaymentPromise();
})
}
.width('100%')
.height('100%')
}
}
五.3.3. 支付结果回调通知（服务器开发）
接收支付信息 ： 支付成功后，Payment Kit服务器会调用开发者提供的回调接口，将支付信息返回给开发者的服务器。
验证支付信息 ： 为确保接收到的支付信息的合法性，商户服务器必须使用SM2算法对返回的支付信息进行验签。
六、拓展
六.1. 申请退款
六.1.1. 退款规则
1. 不支持对同一笔交易单进行并发退款。
2. 订单退款只支持180天内的订单。
3. 申请退款成功不代表退款成功，退款场景是异步处理，需收到退款成功的异步回调通知才表示退款成功。
六.1.2. 接口原型
六.1.3. 请求示例
POST /api/v1/aggr/transactions/refunds HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120\*\*\*","traceId":"202305151442062977847","time":1684132926969,"authId":"120291744647139\*\*\*","headerSign":"BpOBa8o+gJnKG+vHVI7u********************mVuKDV8iPqNJ+Y8b4XDpSi3FHgjozsWH+uLoTSIg=","bodySign":"lHjrX3dv44zyfu+PO1G+oa9tJi2********************EatA8QTjLPsSPKfM="}
Accept: application/json
{
"mercOrderNo": "czl00120240705",
"mercRefundOrderNo": "czl0012024070914",
"reason": "商品质量问题",
"callbackUrl": "<https://www.xxxxxx.com/hw/pay/refund/callback", >
"refundAmount": 200, // 退款2元（单位：分）
"payload": "refund-20240709"
}
六.1.4. 业务流程
1. 用户发起退款 ： 用户提交退款申请（如选择订单、填写原因）。
2. 端侧请求服务端： 客户端将退款信息（原订单号、退款金额等）发送至商户服务端。
3. 服务端调用华为退款接口： 商户服务端验证请求合法性后，调用华为支付退款API发起退款。
4. 华为处理退款： 华为支付异步处理退款，完成后通过回调地址通知商户服务端。
5. 服务端同步结果： 商户服务端更新订单状态，并将结果同步给客户端。
6. 端侧展示结果： 应用展示退款状态（如 “退款中”“退款成功”）。
七、附录
1. 鸿蒙支付服务官方文档：
developer.huawei.com/consumer/cn…
2. 申请华为支付商户入网：
developer.huawei.com/consumer/cn…
3. 华为支付API文档：
