签名授权

数字签名概述

数字签名认证是所有API交易的关键安全机制，包括收款、付款和查询操作（查询状态和查询余额）。此过程通过加密验证确保请求完整性、真实性和不可否认性。

签名生成过程

步骤1: 准备签名数据

收集以下组件用于签名生成：

• X-TIMESTAMP: ISO 8601格式的时间戳
• 商户密钥: 您分配的商户密钥
• 请求体: JSON负载（将被压缩）
• 商户私钥: 您用于签名的RSA私钥

步骤2: 压缩请求体

从JSON请求体中移除所有不必要的空白和格式，以确保一致的签名生成。

压缩前：

{
    "additionalParam": {},
    "area": 10,
    "callbackUrl": "https://docs.smilepayz.com/en/",
    "merchant": {
        "merchantId": "20019"
    },
    "money": {
        "amount": 10000,
        "currency": "IDR"
    },
    "orderNo": "20019c5b63c4b-e34a-4855-9b20-d4b",
    "paymentMethod": "QRIS",
    "purpose": "Purpose For Transaction from Java SDK"
}

压缩后：

{"paymentMethod":"QRIS","orderNo":"20019c5b63c4b-e34a-4855-9b20-d4b","purpose":"Purpose For Transaction from Java SDK","additionalParam":{},"money":{"currency":"IDR","amount":10000},"merchant":{"merchantId":"20019"},"callbackUrl":"https://docs.smilepayz.com/en/","area":10}

步骤3: 组合待签名字符串

通过用管道分隔符连接组件来创建签名字符串：

X-TIMESTAMP + "|" + merchant_secret + "|" + minify(requestBody)

待签名字符串示例：

2024-12-30T18:30:36Z|95b57c46b8c2e068982be23fb669a80612cad68e6ce6ba4f5af9ec20d23bb274|{"paymentMethod":"QRIS","orderNo":"20019c5b63c4b-e34a-4855-9b20-d4b","purpose":"Purpose For Transaction from Java SDK","additionalParam":{},"money":{"currency":"IDR","amount":10000},"merchant":{"merchantId":"20019"},"callbackUrl":"https://docs.smilepayz.com/en/","area":10}

步骤4: 生成数字签名

使用您的RSA私钥对签名字符串应用SHA256withRSA加密。

加密公式：

SHA256withRSA(stringToSign, merchantPrivateKey)

RSA私钥示例：

MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC1d8Zaurk/A0WB1X7CrW+SqsVM4v2ZMGTdqWEQOAKQyY/DZEmgSm7whUMLYfqeKxzzAd3lZHvviyO/V/Ht2i8axtiA5tyDa485IgBy+jO9UHxzI+9CRxnIY5jjDAqAgEvRa0HZEfYHLGlH3IQ4A2a7g8Wm3yqn2prIrgY21nO4+33GuBR0qCpGxth0kV7/RSdhWv3Ff1zkb7yUYn9zfuag9stLf1nw+Ui7hjXL+xGiNRYsDCHOLzKynZxk1cBfqyPY5YMTIjQik4cI+YfM4BMN8bmTB1y3z9sdfbHVTI/PD/fbDzvfK7S/XJvY2bj1TwNeYCHcd5Dx6MYiO12rfA5XAgMBAAECggEASRpMJMat042c1ZXM793wYXQ78SJMKQcOyyDtwhveJLeeG4duBY2WrXvxq0c4L7mMevSYkE1vg+tYZj+mbTwE19Oc6iiWUrbkxo5FAgx7BVvEFpo2S0vbPhepQmXaYTPN1zpPF4QdyXwBmXpjJTFxlD6cRAII6/+rdQZt6G9xxOWUq6bbENNUc6y+N+97oPPwrzLZGYADfusM735Mlx3j8xTGLSHTh2d8e5epwKcSW+ZvBbiM30ZeO+M5bh6zgZrHpPQNJAOsEDuVk5vjuC5O+i81YwP702GAE50zI9Ysr4QMS3QQGe2jwpJAmMjvO6/MRv/6De83NJ6Y70+00OONcQKBgQDtP+sQOyKRErCN9ePmu6FBfzMZcTC5vXQpA0kW7vUMKyQR537appYcOb5DPJDgUqqyNcr8vIqadR6OW0thkfRyb+L/elOyS/XnVbFc6RA9DW/KV4xm68LUX9oRqfgy5YOESEEA2igEh8IdqfkIRCZ3g7xrQUmb3gq0BM2/hnxyHwKBgQDDz0Slbw2Pv820CSheZi8HQf3sEFe0JDHKo2KAHX9rTvFEF3xsT+UZh6pcHUcesYlVlJM2Ciejq4dmiOnvGIKtkqtcLfioVbPrDP2HlDtIT3mSC7sL6VdWLxYz/l0EVjsR2KMVwXD42jcjz3e5bDIi98Z8G4Bx6cu6pwlBtfMMyQKBgHJhWoacu/GNPSlz3sgitX/KP2yIsaEawaH0P4ya7/FJ6z3mibYIkl5RSHVKAd7ke/8nCBIJJBmLVYv0X8dOgreZUasx4qAXFxrMqZHNm1KT4819n+cOywNwosXZWBvRozJnU0+B3cExYljC1ZkyogkErhZXh5Fp32ci2b74q46pAoGANWyixSRkpdjmLf3lpsPohulpd3QKCdtqPmiPonbp4gRa7YIe74po7qtGPvW6BtTXrKLp+2+P2yccvUwTz6l3VhZTbMYaNwuTGEmmDszR0+vjNoa+1QQoURpty2fWRy2j1j2uWWw6/5rCOqILf2rWzxWdcRUr2Wi5rkaOzv/uvYkCgYEAlFV6huNhi1NIIg5gkTS0kmxnIUWu8XIT9IgZWMrhR7TvImVISoormE9LdISgMBz+J5YJxhAZbxVxlUJrsl+HVcS81gmUkeoIpTA+iKUzbD9gAPjEdqVylzN8A9uNIkkb5Cf4BWYfEyMaLfBuiHDlKDcBjz4cJbcom3RVGacghKc=

生成的签名示例：

RvWeMDztovywfyarzFEUUDUo6F5f0weT+X2FTfjJ/KVxyDJJ4PHddsqHx0h98/ZOofCaADx8MaoG1rTaHd+5BkJPPlwrwG62oZygjNOV2gJ0rstTBWZOQgORkTjvBj91KQgzWRpT6yLJaeRaJRS2YfRPGA5MH7ieGWkocPXNRw+v0HolPMren+y69sZmVVXeRs9SXV9QpCZP8zNHPEQt75zgVKSr5/GmkfTCgFPNz/+23MpVMigwpOcifxEDwN+KzfdnQxjYi6n01qztb1skXOTlIRrhDkJSRhOzrDHQEwnp/6XEjyZaOV/XXSJtMsr85Yl97cF0daW1ALkuF7NHew==

步骤5: 在HTTP头部包含签名

将生成的签名添加到HTTP请求头部：

X-SIGNATURE: RvWeMDztovywfyarzFEUUDUo6F5f0weT+X2FTfjJ/KVxyDJJ4PHddsqHx0h98/ZOofCaADx8MaoG1rTaHd+5BkJPPlwrwG62oZygjNOV2gJ0rstTBWZOQgORkTjvBj91KQgzWRpT6yLJaeRaJRS2YfRPGA5MH7ieGWkocPXNRw+v0HolPMren+y69sZmVVXeRs9SXV9QpCZP8zNHPEQt75zgVKSr5/GmkfTCgFPNz/+23MpVMigwpOcifxEDwN+KzfdnQxjYi6n01qztb1skXOTlIRrhDkJSRhOzrDHQEwnp/6XEjyZaOV/XXSJtMsr85Yl97cF0daW1ALkuF7NHew==

签名验证

用于验证的RSA公钥

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtXfGWrq5PwNFgdV+wq1vkqrFTOL9mTBk3alhEDgCkMmPw2RJoEpu8IVDC2H6nisc8wHd5WR774sjv1fx7dovGsbYgObcg2uPOSIAcvozvVB8cyPvQkcZyGOY4wwKgIBL0WtB2RH2ByxpR9yEOANmu4PFpt8qp9qayK4GNtZzuPt9xrgUdKgqRsbYdJFe/0UnYVr9xX9c5G+8lGJ/c37moPbLS39Z8PlIu4Y1y/sRojUWLAwhzi8ysp2cZNXAX6sj2OWDEyI0IpOHCPmHzOATDfG5kwdct8/bHX2x1UyPzw/32w873yu0v1yb2Nm49U8DXmAh3HeQ8ejGIjtdq3wOVwIDAQAB

开发工具

JSON压缩工具

工具	URL	使用方法
JSON Formatter	https://jsonformatter.org/json-minify	选择"Minify JSON"选项

安全最佳实践

密钥管理

• 安全存储: 将私钥存储在安全、加密的存储中
• 密钥轮换: 定期轮换RSA密钥对
• 访问控制: 限制私钥访问权限，仅授权人员可访问
• 备份: 维护私钥的安全备份

实施指南

• 时间戳准确性: 确保X-TIMESTAMP与服务器时间相差在±5分钟内
• 请求完整性: 签名生成后切勿修改请求体
• 错误处理: 为签名验证失败实施适当的错误处理
• 日志记录: 记录签名生成尝试以用于审计目的

常见问题和解决方案

• 签名不匹配: 验证所有组件顺序和格式是否正确
• 时间戳问题: 确保系统时钟与NTP服务器同步
• 密钥格式: 验证RSA密钥格式和编码
• 编码问题: 确保所有字符串组件使用正确的UTF-8编码

合规性和标准

加密标准

• 算法: SHA256withRSA（SHA-256哈希与RSA签名）
• 密钥大小: 建议最小2048位RSA密钥
• 编码: 签名输出使用Base64编码
• 格式: 私钥使用PKCS#8格式

审计要求

• 签名日志: 维护所有签名生成和验证的日志
• 密钥使用: 跟踪密钥使用情况和轮换计划
• 访问日志: 监控对加密材料的访问
• 合规报告: 为监管要求生成合规报告