粤收付加签验签规则

协议规则

传输方式：采用HTTPS传输
提交方式：POST 或 GET
内容类型：application/json
字符编码：UTF-8
签名算法：RSA2（SHA256withRSA）

参数规范

交易金额：默认为人民币交易，单位为分，参数值不能带小数。
时间参数：所有涉及时间参数均使用精确到毫秒的13位数值，如：1622016572190。时间戳具体是指从格林尼治时间1970年01月01日00时00分00秒起至现在的毫秒数。

RSA2签名算法

签名生成的通用步骤如下

第一步：参数处理

所有发送或接收到的JSON数据为集合M，将集合M内非空参数值的参数按参数名ASCII码从小到大排序（字典序），再拼接URL键值对格式（即key1=value1&key2=value2…）得到待签名字串stringA
（其中请求参数sign并不参与签名）。

特别注意以下重要规则：
◆ 参数名ASCII码从小到大排序（字典序）；
◆ 如果参数的值为空不参与签名；
◆ 参数名区分大小写；
◆ 验证调用返回或支付中心主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验。
◆ 支付中心接口可能增加字段，验证签名时必须支持增加的扩展字段
◆ 注意：RSA2签名时，拼接的字符串末尾不需要添加API密钥，直接对stringA进行签名即可

第二步：RSA2签名

使用商户的RSA私钥，对stringA进行SHA256withRSA签名，签名结果转换为Base64编码字符串，得到最终的签名值signValue。

签名示例

1. 请求参数示例

2. 待签名字符串（注意末尾不加key）

amount=1&appId=68a40a59e4b0bf61830a5687&body=商品描述&channelExtra={"authCode":"2088622213378244"}&clientIp=175.0.227.20&currency=CNY&mchNo=M1755581016&mchOrderNo=P1957679439693283330&notifyUrl=https://www.cnyepay.com&reqTime=1694051706&signType=RSA2&subject=商品标题&version=1.0&wayCode=ALI_JSAPI

3. RSA2签名流程

4. 签名结果示例（Base64编码）

RqO5SEV50TTM1sHqGZnKRL2dGIEjQNjmSlKCiuKA7dZ4zF+7eHzZtB6VipF530c0XssCyuLIR8n7IUs5i1FCbdlDrGeFUH+jWTalvw60/6AaD1A6MUI/9HLDApIGzBCXGDxY2QMrxsLlbqEhbdCkkXdkRP8mRjL1UJIYwqGW+q61R8P5wECCThh18JoU8okWNsaJHeEc0uKDlI0PGYg+K2z+xJl60uroHW0ZKR4uJ02uHHBWN52fpxjD1on5tsr2n3EHXX1XNh6Sdqh/+yMDYrE6yTwxhynTqTLJk1V9mqNPyQW73lDR2obAGLz/AkFeTfcOaKB6u0MKPuU9Rr6InA==

5. 最终请求参数

{
  "amount": 1,
  "mchOrderNo": "P1957679439693283330",
  "subject": "商品标题",
  "wayCode": "ALI_JSAPI",
  "sign": "RqO5SEV50TTM1sHqGZnKRL2dGIEjQNjmSlKCiuKA7dZ4zF+7eHzZtB6VipF530c0XssCyuLIR8n7IUs5i1FCbdlDrGeFUH+jWTalvw60/6AaD1A6MUI/9HLDApIGzBCXGDxY2QMrxsLlbqEhbdCkkXdkRP8mRjL1UJIYwqGW+q61R8P5wECCThh18JoU8okWNsaJHeEc0uKDlI0PGYg+K2z+xJl60uroHW0ZKR4uJ02uHHBWN52fpxjD1on5tsr2n3EHXX1XNh6Sdqh/+yMDYrE6yTwxhynTqTLJk1V9mqNPyQW73lDR2obAGLz/AkFeTfcOaKB6u0MKPuU9Rr6InA==",
  "reqTime": "1694051706",
  "body": "商品描述",
  "version": "1.0",
  "channelExtra": "{\"authCode\":\"2088622213378244\"}",
  "appId": "68a40a59e4b0bf61830a5687",
  "clientIp": "175.0.227.20",
  "notifyUrl": "https://www.cnyepay.com",
  "signType": "RSA2",
  "currency": "CNY",
  "mchNo": "M1755581016"
}

RSA密钥管理

密钥生成

建议使用【支付宝开发者工具】生成密钥对

密钥格式

私钥格式：支持PKCS#8（PRIVATE KEY）格式

公钥格式：标准公钥格式（PUBLIC KEY）

密钥长度：建议使用2048位或以上

密钥配置

商户私钥：用于生成签名，必须妥善保管，不可泄露

商户公钥：提供给粤收付，用于验证商户签名

粤收付公钥：粤收付提供，用于验证平台返回数据的签名

签名验证

验证平台返回数据

当收到支付网关返回的数据时，需要使用平台公钥验证签名：

注意事项

字符编码：所有参数必须使用UTF-8编码

大小写敏感：参数名和参数值都区分大小写

签名编码：RSA2签名结果必须使用Base64编码

密钥安全：私钥必须安全保管，建议定期更换

时间戳：reqTime使用13位毫秒时间戳

货币代码：currency必须使用大写，如"CNY"

空值处理：参数值为null、undefined或空字符串时不参与签名

常见问题

Q1: RSA2签名失败

检查私钥格式是否正确（PKCS#8）

确认私钥是否完整，包含头尾标识

验证待签名字符串是否正确拼接

Q2: 签名验证失败

确认公私钥是否匹配

检查签名字符串拼接规则是否一致

确认签名结果是否正确进行了Base64编码

Q3: 参数排序问题

必须严格按照ASCII码从小到大排序

使用编程语言的标准排序函数即可

商户完成入网后需要使用管理员邮箱向粤收付发送邮件，邮件内附商户RSA公钥、商户号、商户名称、商户应用ID等信息用于配置，若同步发送了商户RSA私钥将不予配置，且需要更换RSA密钥再次发送新的邮件才予以配置；
粤收付平台公钥请于粤收付商户后台获取用于回调验签；
若商户需要变更商户公钥信息需将新的商户信息、公钥、盖章版密钥变更书给予粤收付方可操作变更。

协议规则#

参数规范#

RSA2签名算法#

第一步：参数处理#

第二步：RSA2签名#

签名示例#

1. 请求参数示例#

2. 待签名字符串（注意末尾不加key）#

3. RSA2签名流程#

4. 签名结果示例（Base64编码）#

5. 最终请求参数#

RSA密钥管理#

密钥生成#

密钥格式#

密钥配置#

签名验证#

验证平台返回数据#

注意事项#

常见问题#

Q1: RSA2签名失败#

Q2: 签名验证失败#

Q3: 参数排序问题#