快速开始

本页给出最短接入流程。生产接入前仍需要完整阅读签名、加密、通知和错误处理页面。

1. 准备凭证

在商户技术中心创建 Open API 凭证，保存以下信息：

名称	用途
merchant_no	商户号，请求头 X-Mch-Id。
secret_key	HMAC-SHA256 签名密钥，只在创建或轮换时返回一次。
platform_public_key	平台公钥，用于加密 Open POST 请求的内容密钥。
merchant_private_key	商户私钥，用于解密平台响应和商户通知。

商户还需要在技术中心录入 merchant_public_key，平台用它加密 Open POST 响应和通知。

2. 生成业务 JSON

例如创建收款订单的业务 JSON：

{
  "merchant_order_no": "PAY-OPEN-202607030001",
  "amount": "20.000",
  "currency_code": "USD",
  "scene": "qr",
  "notify_url": "https://merchant.example.com/pay/notify",
  "subject": "PayOpenOrder",
  "client_ip": "127.0.0.1",
  "payer": {
    "merchant_user_id": "payer-10001",
    "account_type": 3,
    "account_no": "openid-10001",
    "account_name": "Payer Name",
    "identity_no": "ID-10001",
    "mobile": "13800000001",
    "email": "[email protected]"
  }
}

这个 JSON 是加密前的业务明文，不是最终 HTTP body。

3. 加密 POST 信封

1. 随机生成 32 字节 content_key。
2. 使用 platform_public_key 对 content_key 做 RSA-OAEP 加密，得到 encrypted_key。
3. 使用 content_key 对业务 JSON 做 AES-256-GCM 加密，得到 biz_content。
4. 最终 HTTP body 只发送：

{
  "encrypted_key": "base64(RSA-OAEP(platform_public_key, content_key))",
  "biz_content": "base64(aes_gcm_nonce || aes_gcm_ciphertext || aes_gcm_tag)"
}

4. 签名请求

所有请求都携带：

X-Mch-Id: merchant_no
X-Timestamp: Unix 秒
X-Nonce: 随机串
X-Signature: HMAC-SHA256 小写 hex
X-Request-Id: 商户请求 ID，可选

签名串固定 6 行：

METHOD
PATH
MCH_ID
TIMESTAMP
NONCE
PAYLOAD_DIGEST

POST 的 PAYLOAD_DIGEST 基于最终传输的加密信封 JSON 计算，不基于业务明文 JSON。

5. 解密响应

Open POST 成功响应的 data 仍是加密信封：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "encrypted_key": "...",
    "biz_content": "..."
  }
}

商户处理顺序：先验证响应头签名，再用商户私钥解密 data.encrypted_key，最后用解出的 content_key 解密 data.biz_content。

6. 处理通知

平台向订单里的 notify_url 发起加密通知。商户验签并解密成功后返回 HTTP 2xx。非 2xx 会触发平台重试。