# 公共说明
#### HTTPS安全要求
* 所有的API请求必须使用HTTPS。
* 支持的TLS协议版本：1.2 / 1.3。
* 支持的加密套件列表：
```
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
```
#### HTTP方法说明
当前Payment Kit对外接口涉及GET及POST两种HTTP METHOD。
* GET：对应于查询场景。适用于从服务器查询资源数据，如查询订单信息、查询签约信息等。
* POST：对应于新建/更新资源场景，如预下单、退款请求等。
#### 数据格式
请求和响应报文统一使用JSON格式。
#### 字符编码
Payment Kit所有请求默认支持UTF-8编码，如采用其他编码格式的报文可能导致验签失败、字段解析失败等问题。
HTTP METHOD方式为GET的接口请求，请求URL如涉及参数拼接，拼接后完整的请求URL不建议带特殊字符。如有需要，建议对URL中的特殊字符进行编码处理。URL特殊字符参考但不限于：+, 空格, ?, %, #, \&, =
#### 认证授权
* 认证(Authentication)：认证操作确认调用者身份，防抵赖和数据篡改。所有对商户开放接口均需要商户在请求头中传递[PayMercAuth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#paymercauth)字段，在开放网关认证通过后方可进行后续流程。
* 授权(Authorization)：授权确保给定接口仅特定调用者才有权限调用。部分接口仅特定商户申请开通后方可使用。
#### 签名规则
签名场景： 商户云侧请求的请求头中参数签名。
签名算法： SHA256WithRSA/PSS 或者 SM2。
开发步骤：
1. 筛选：排除请求JSON字符串中sign字段，只保留sign以外的其他字段。
2. 排序拼接：按key值的ASCII码顺序排序，并使用\&拼接，列表场景使用符号"="连接。
具体可参考[示例代码](https://gitcode.com/HarmonyOS_Samples/paymentkit-sample-code-serverdemo-java)引入华为支付提供[Maven依赖（pay-java）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-server-connect#集成maven依赖)中SignStringUtil.java类的signString方法，排序拼接结果示例如下：
```
"allocationType=DELAY_ORDER_ALLOCATION&callbackUrl=https://www.xxxxxx.com/hw/pay/callback¤cy=CNY&mercNo=xxxxxx&mercOrderNo=xxxxxx&totalAmount=2&tradeSummary=杂志报刊"
```
3. 签名：调用给定算法对排序后的串完成签名。
SHA256WithRSA/PSS： 具体可参考[示例代码](https://gitcode.com/HarmonyOS_Samples/paymentkit-sample-code-serverdemo-java)引入华为支付提供[Maven依赖（pay-java）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-server-connect#集成maven依赖)中RSAUtils.java类的signByRSAWithPSS方法。
SM2： 具体可参考[Maven依赖（pay-java）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-server-connect#集成maven依赖)中Sm2Utils.java类中的sign方法。
加签内容参考：
```
POST请求：POST https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/preorder/create/app
{
"appId": "5765880207854262xxx",
"callbackUrl": "https://www.xxx.com/hw_notify",
"currency": "CNY",
"mercNo": "101723200xxx",
"mercOrderNo": "2405171027547xxx",
"payload": "shop|h8ahnJA8xxRXVw",
"totalAmount": 5,
"tradeSummary": "test",
"subOrders": [
{
"mercNo": "101723200xxx",
"mercOrderNo": "abcxxx1"
},
{
"mercNo": "101723201xxx",
"mercOrderNo": "abcxxx2"
}
]
}
加签内容：appId=5765880207854262xxx&callbackUrl=https://www.xxx.com/hw_notify¤cy=CNY&mercNo=101723200xxx&mercOrderNo=2405171027547xxx&payload=shop|h8ahnJA8xxRXVw&subOrders=mercNo=101723200xxx&mercOrderNo=abcxxx1,mercNo=101723201xxx&mercOrderNo=abcxxx2&totalAmount=5&tradeSummary=test
GET请求：GET https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/transactions/merc-orders/20240507000000041809599950090xxx?mercNo=101540000089&sdkVersion=1.0.0
加签内容：/api/v2/aggr/transactions/merc-orders/20240507000000041809599950090xxx?mercNo=101540000089&sdkVersion=1.0.0
```
字段值设置为null时，字段可不参与签名，设置为空字符时，则必须参与签名。
#### 常用语言SHA256WithRSA/PSS加签示例代码参考
go语言
加签实现示例代码：
```
// 排序拼接示例
import (
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"sort"
"strings"
)
// GenerateSignData 生成待签名字符串
// 步骤一：筛选，排除sign字段
// 步骤二：排序拼接，按key的ascii码顺序排序，使用&连接
func (s *SignatureUtils) GenerateSignData(params map[string]interface{}) string {
return s.buildSignData(params)
}
// buildSignData 递归构建签名字符串
func (s *SignatureUtils) buildSignData(params interface{}) string {
switch v := params.(type) {
case map[string]interface{}:
return s.buildMapSignData(v)
case []interface{}:
return s.buildArraySignData(v)
default:
return fmt.Sprintf("%v", v)
}
}
// buildMapSignData 处理Map类型数据
func (s *SignatureUtils) buildMapSignData(params map[string]interface{}) string {
// 排序key
var keys []string
for k := range params {
// 排除sign字段
if k == "sign" {
continue
}
keys = append(keys, k)
}
sort.Strings(keys)
var parts []string
for _, key := range keys {
value := params[key]
// null值不参与签名
if value == nil {
continue
}
// 空字符串参与签名
strValue := s.buildSignData(value)
parts = append(parts, fmt.Sprintf("%s=%s", key, strValue))
}
return strings.Join(parts, "&")
}
// buildArraySignData 处理数组类型数据
func (s *SignatureUtils) buildArraySignData(arr []interface{}) string {
var parts []string
for _, item := range arr {
if item == nil {
continue
}
parts = append(parts, s.buildSignData(item))
}
return strings.Join(parts, ",")
}
// 加签示例
package main
import (
"crypto"
"crypto/rand"
"crypto/rsa"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"fmt"
"testing"
)
func signSha256WithRsaPSS(message, privateKeyStr string) (string, error) {
privateKey, err := getPrivateKey(privateKeyStr)
if err != nil {
return "", err
}
hasher := sha256.New()
hasher.Write([]byte(message))
hashedMessage := hasher.Sum(nil)
opts := rsa.PSSOptions{
SaltLength: rsa.PSSSaltLengthEqualsHash,
Hash: crypto.SHA256,
}
signature, err := rsa.SignPSS(rand.Reader, privateKey, crypto.SHA256, hashedMessage, &opts)
if err != nil {
return "", err
}
return base64.StdEncoding.EncodeToString(signature), nil
}
func getPrivateKey(privateKeyStr string) (*rsa.PrivateKey, error) {
decoded, err := base64.StdEncoding.DecodeString(privateKeyStr)
if err != nil {
return nil, err
}
privateKey, err := x509.ParsePKCS8PrivateKey(decoded)
if err != nil {
return nil, err
}
rsaPrivateKey, ok := privateKey.(*rsa.PrivateKey)
if !ok {
return nil, err
}
return rsaPrivateKey, nil
}
func TestRsaSign(t *testing.T) {
signature, err := signSha256WithRsaPSS("加签排序拼接内容","私钥")
fmt.Println(signature, err)
}
```
JavaScript语言
javascript可通过jsrsasign模块实现，如已安装node环境，可执行如下命令安装jsrsasign模块。
```
npm install jsrsasign
```
加签实现示例代码：
```
// 排序拼接示例
/**
* 递归构建签名字符串
* @param {*} data 数据
* @returns {string} 签名字符串
*/
buildSignData(data) {
if (data === null || data === undefined) {
return '';
}
if (typeof data === 'object' && !Array.isArray(data)) {
return this.buildMapSignData(data);
}
if (Array.isArray(data)) {
return this.buildArraySignData(data);
}
return String(data);
}
/**
* 处理Map类型数据
* @param {Object} params 参数对象
* @returns {string} 签名字符串
*/
buildMapSignData(params) {
// 排序key
const keys = Object.keys(params)
.filter(key => key !== 'sign') // 排除sign字段
.sort();
const parts = [];
for (const key of keys) {
const value = params[key];
// null值不参与签名
if (value === null || value === undefined) {
continue;
}
// 空字符串参与签名
const strValue = this.buildSignData(value);
parts.push(`${key}=${strValue}`);
}
return parts.join('&');
}
/**
* 处理数组类型数据
* @param {Array} arr 数组
* @returns {string} 签名字符串
*/
buildArraySignData(arr) {
const parts = [];
for (const item of arr) {
if (item === null || item === undefined) {
continue;
}
parts.push(this.buildSignData(item));
}
return parts.join(',');
}
// 加签示例
const jsrsasign = require('jsrsasign');
function signSha256WithRsaPSS(plainData, privateStr) {
let rsa = new jsrsasign.RSAKey();
// PEM 格式的私钥
const priKey = `-----BEGIN PRIVATE KEY-----\n${privateStr}\n-----END PRIVATE KEY-----\n`;
rsa = jsrsasign.KEYUTIL.getKey(priKey);
const sig = new jsrsasign.KJUR.crypto.Signature({
alg: 'SHA256withRSAandMGF1',
});
sig.init(rsa);
sig.updateString(plainData);
return jsrsasign.hextob64(sig.sign());
}
let signature = signSha256WithRsaPSS("加签排序拼接内容","私钥");
console.info(signature)
```
python语言
python可通过cryptography模块实现，可先执行如下命令安装cryptography模块：
```
pip install cryptography
```
加签实现示例代码：
```
# 排序拼接示例
def generate_sign_data(self, params):
"""
生成待签名字符串
步骤一：筛选，排除sign字段
步骤二：排序拼接，按key的ascii码顺序排序，使用&连接
Args:
params: 参数字典
Returns:
str: 待签名字符串
"""
return self._build_sign_data(params)
def _build_sign_data(self, data):
"""
递归构建签名字符串
Args:
data: 数据
Returns:
str: 签名字符串
"""
if data is None:
return ''
if isinstance(data, dict):
return self._build_map_sign_data(data)
if isinstance(data, (list, tuple)):
return self._build_array_sign_data(data)
return str(data)
def _build_map_sign_data(self, params):
"""
处理字典类型数据
Args:
params: 参数字典
Returns:
str: 签名字符串
"""
# 排序key，排除sign字段
keys = sorted([k for k in params.keys() if k != 'sign'])
parts = []
for key in keys:
value = params[key]
# None值不参与签名
if value is None:
continue
# 空字符串参与签名
str_value = self._build_sign_data(value)
parts.append(f"{key}={str_value}")
return '&'.join(parts)
def _build_array_sign_data(self, arr):
"""
处理数组类型数据
Args:
arr: 数组
Returns:
str: 签名字符串
"""
parts = []
for item in arr:
if item is None:
continue
parts.append(self._build_sign_data(item))
return ','.join(parts)
# 加签示例
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.serialization import load_pem_private_key, load_pem_public_key
def signSha256WithRsaPSS(private_key_str, message):
# PEM 格式的私钥
prikey_content = "-----BEGIN PRIVATE KEY-----\n" + private_key_str +"\n-----END PRIVATE KEY-----\n";
private_key = load_pem_private_key(data=prikey_content.encode("utf-8"), password=None, backend=default_backend())
# 使用 RSA-PSS 算法生成签名
signature = private_key.sign(
message.encode("utf-8"),
padding.PSS(
mgf=padding.MGF1(hashes.SHA256()),
salt_length=padding.PSS.DIGEST_LENGTH
),
hashes.SHA256()
)
return base64.b64encode(signature).decode('utf-8')
message = "加签排序拼接内容"
private_key_str = "私钥"
signature = signSha256WithRsaPSS(private_key_str, message)
print(signature)
```
php语言
php可通过phpseclib加密库实现，如已安装composer环境，可先通过以下命令导入phpseclib：
```
composer require phpseclib/phpseclib
```
phpseclib2加签实现示例代码：
```
// 排序拼接示例
class SignatureUtils
{
/**
* 生成待签名字符串
* 步骤一：筛选，排除sign字段
* 步骤二：排序拼接，按key的ascii码顺序排序，使用&连接
*
* @param array $params 参数数组
* @return string 待签名字符串
*/
public function generateSignData($params)
{
return $this->buildSignData($params);
}
/**
* 递归构建签名字符串
*
* @param mixed $data 数据
* @return string 签名字符串
*/
private function buildSignData($data)
{
if ($data === null) {
return '';
}
if (is_array($data)) {
// 判断是否为关联数组（Map）
if ($this->isAssocArray($data)) {
return $this->buildMapSignData($data);
} else {
return $this->buildArraySignData($data);
}
}
return (string)$data;
}
/**
* 判断是否为关联数组
*
* @param array $arr 数组
* @return bool
*/
private function isAssocArray($arr)
{
if (empty($arr)) {
return false;
}
return array_keys($arr) !== range(0, count($arr) - 1);
}
/**
* 处理Map类型数据
*
* @param array $params 参数数组
* @return string 签名字符串
*/
private function buildMapSignData($params)
{
// 排序key，排除sign字段
$keys = array_keys($params);
$keys = array_filter($keys, function($key) {
return $key !== 'sign';
});
sort($keys);
$parts = [];
foreach ($keys as $key) {
$value = $params[$key];
// null值不参与签名
if ($value === null) {
continue;
}
// 空字符串参与签名
$strValue = $this->buildSignData($value);
$parts[] = $key . '=' . $strValue;
}
return implode('&', $parts);
}
/**
* 处理数组类型数据
*
* @param array $arr 数组
* @return string 签名字符串
*/
private function buildArraySignData($arr)
{
$parts = [];
foreach ($arr as $item) {
if ($item === null) {
continue;
}
$parts[] = $this->buildSignData($item);
}
return implode(',', $parts);
}
/**
* Base64转Hex
*
* @param string $base64String Base64字符串
* @return string Hex字符串
*/
private function base64ToHex($base64String)
{
$bytes = base64_decode($base64String);
return bin2hex($bytes);
}
/**
* 解析JSON字符串为数组
*
* @param string $jsonStr JSON字符串
* @return array 数组
*/
public function parseJSON($jsonStr)
{
return json_decode($jsonStr, true);
}
/**
* 从JSON字符串生成待签名字符串
*
* @param string $jsonStr JSON字符串
* @return string 待签名字符串
*/
public function generateSignDataFromJSON($jsonStr)
{
$params = $this->parseJSON($jsonStr);
return $this->generateSignData($params);
}
public function testExcludeSignField()
{
$params = [
'appId' => '5765880207854262xxx',
'callbackUrl' => 'https://www.xxx.com/hw_notify',
'sign' => 'xxxxx', // sign字段应被排除
'currency' => 'CNY'
];
$signData = $this-> generateSignData($params);
echo "[testExcludeSignField] Sign data without sign field: " . $signData . "\n";
}
}
// 加签示例
loadKey($privateKey, $password = false);
$signer->setHash('sha256');
$signer->setSignatureMode(RSA::SIGNATURE_PSS);
$signer->setMGFHash('sha256');
$signature = $signer->sign($content);
$sign = base64_encode($signature);
return $sign;
} catch (Exception $e) {
echo $e->getMessage();
}
return null;
}
$data = "加签排序拼接内容";
$privateKeyStr = "私钥";
echo signSha256WithRsaPSS($data, $privateKeyStr)
?>
```
phpseclib3加签实现示例代码：
```
withPadding(RSA::SIGNATURE_PSS);
return base64_encode($private->sign($data));
}
$data = "加签排序拼接内容";
$privateKeyStr = "私钥";
echo signSha256WithRsaPSS($data, $privateKeyStr);
?>
```
C#语言
C#可通过BouncyCastle库来实现，如已安装 [.NET SDK](https://dotnet.microsoft.com/download)，可先执行如下命令添加BouncyCastle：
```
dotnet add package BouncyCastle
```
加签实现示例代码：
```
// 排序拼接示例
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Linq;
namespace PaySignature
{
///
/// 签名工具类
///
public class SignatureUtils
{
///
/// 生成待签名字符串
/// 步骤一：筛选，排除sign字段
/// 步骤二：排序拼接，按key的ascii码顺序排序，使用&连接
///
/// 参数字典
/// 待签名字符串
public string GenerateSignData(Dictionary parameters)
{
return BuildSignData(parameters);
}
///
/// 递归构建签名字符串
///
/// 数据
/// 签名字符串
private string BuildSignData(object data)
{
if (data == null)
{
return string.Empty;
}
if (data is Dictionary dict)
{
return BuildMapSignData(dict);
}
if (data is List