CodePay RSA 签名认证机制

Online Payment (Hosted Checkout) 集成所需的认证体系详解

更新: 2026-02-07

一、三把密钥的分工

CodePay 的 RSA 签名认证涉及 3 把密钥，分属两对 RSA 密钥对：

密钥对关系图

二、我方发请求 → CodePay（创建支付订单）

签名流程详解

1组装请求数据

{
  "merchant_no": "M123456",
  "amount": 5000,
  "currency": "USD",
  "order_id": "DEP_20260207_001",
  "notify_url": "https://api.celoria.ai/api/webhooks/codepay",
  "return_url": "https://celoria.ai/booking/success"
}

2参数排序拼接

把所有参数按 key 的字母顺序排列，用 & 拼接成字符串：

amount=5000¤cy=USD&merchant_no=M123456¬ify_url=https://api.celoria.ai/api/webhooks/codepay&order_id=DEP_20260207_001&return_url=https://celoria.ai/booking/success

3RSA 签名

用 app_rsa_private_key 对上面的字符串做 SHA256WithRSA 签名：

const crypto = require('crypto');

function signRequest(params, privateKey) {
  // 1. 过滤空值，按 key 排序
  const sorted = Object.keys(params)
    .filter(k => params[k] !== '' && params[k] !== null && params[k] !== undefined)
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&');

  // 2. 用私钥签名 (SHA256WithRSA)
  const sign = crypto.createSign('RSA-SHA256');
  sign.update(sorted);
  return sign.sign(privateKey, 'base64');
}

4发送请求

把签名值放入 sign 字段，连同 sign_type: "RSA2" 一起发送：

{
  "merchant_no": "M123456",
  "amount": 5000,
  "currency": "USD",
  "order_id": "DEP_20260207_001",
  "notify_url": "https://api.celoria.ai/api/webhooks/codepay",
  "return_url": "https://celoria.ai/booking/success",
  "sign_type": "RSA2",
  "sign": "a3f8d2e1b9c7..."
}

三、CodePay → 我方（Webhook 回调通知）

验签代码

function verifyCodePaySignature(params, sign, gatewayPublicKey) {
  // 1. 取出 sign 和 sign_type，其余参数排序拼接
  const filtered = Object.keys(params)
    .filter(k => k !== 'sign' && k !== 'sign_type')
    .filter(k => params[k] !== '' && params[k] !== null)
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&');

  // 2. 用 CodePay 公钥验证签名
  const verify = crypto.createVerify('RSA-SHA256');
  verify.update(filtered);
  return verify.verify(gatewayPublicKey, sign, 'base64');
}

四、完整定金支付流程

五、环境变量配置

Online Payment 需要在 .env 中新增以下配置（与现有 Cloud Mode 配置并存）：

# ===== CodePay Online Payment (Hosted Checkout) =====
CODEPAY_APPID=xxx                          # CodePay 分配的应用 ID
CODEPAY_APP_RSA_PRIVATE_KEY=xxx            # 我方 RSA 私钥 (PEM 格式，单行 base64)
CODEPAY_GATEWAY_RSA_PUBLIC_KEY=xxx         # CodePay 网关公钥 (PEM 格式)
CODEPAY_SIGN_TYPE=RSA2                     # 签名算法 (SHA256WithRSA)

# ===== 以下为已有配置（Cloud Mode 复用） =====
# CODEPAY_MERCHANT_NO=M123456             # 商户号（两种模式共用）
# CODEPAY_WEBHOOK_SECRET=xxx              # 仅 Cloud Mode HMAC 验签用

六、密钥生成步骤

生成 RSA 2048 密钥对

# 1. 生成私钥
openssl genrsa -out app_rsa_private_key.pem 2048

# 2. 从私钥导出公钥
openssl rsa -in app_rsa_private_key.pem -pubout -out app_rsa_public_key.pem

# 3. 查看公钥内容（用于上传到 CodePay 商户后台）
cat app_rsa_public_key.pem

上传与下载

七、与现有 Cloud Mode 的对比

八、参考文档

• CodePay API Security — 认证方式说明
• CodePay Hosted Checkout — 托管支付页集成指南
• CodePay Web Payment — Web 支付集成指南
• Payment Callbacks Checklist — Webhook 回调实现清单
• 项目内部: specs/payments/015-pos-payment/codepay-cloud-integration.md — Cloud Mode 集成方案
• 项目内部: specs/053-booking-deposit-cancellation-policy/spec.md — 定金与退订政策 Spec

CodePay RSA 签名认证机制文档
适用于: Guest App 定金支付 (Hosted Checkout) 集成
更新: 2026-02-07