Skip to content

SDK 总览与下载

平台为五种语言提供官方 SDK:PHP、Python、Node.js、Go、Java。每个 SDK 都是单文件源码,直接复制进你的项目即可使用,不发布到 Composer / PyPI / npm 等公共仓库。

所有 SDK 实现同一套 v2 协议:RSA-OAEP(SHA-1)加密、SHA256withRSA 签名、时间戳 + nonce 防重放。协议细节见加密与签名协议

五语言支持一览

各语言 SDK 的核心加解密 / 签名 / 验签能力完全一致,差异主要在 getToken 与 HTTP 的封装程度

语言源码文件依赖能力概述文档
PHPsdk/php/AnonyV2Client.phpopenssl 扩展getToken($secret) 全自动(内含 HTTP 调用);post() 一步完成加密、签名、发送、验签、解密PHP SDK
Pythonsdk/python/anony_v2.pycryptographyauth_header() 计算 getToken 鉴权头 + build_request() 构造加密签名请求 + verify_response() 验签解密;HTTP 用你自选的库(如 requestsPython SDK
Node.jssdk/node/anony_v2.js内置 crypto(getToken 需 Node ≥ 18)getToken(secret) 全自动;buildRequest() + verifyResponse() 配合 fetch 使用Node.js SDK
Gosdk/go/anonyv2.go标准库加解密 / 签名原语:Encrypt / Decrypt / Sign / Verify / Canonical / NewNonce / AuthHeader;HTTP 与 JSON 序列化由你自选的库完成Go SDK
Javasdk/java/AnonyV2Client.javaJDK 标准库静态方法原语:encrypt / decrypt / sign / verify / canonical / newNonce / buildHeaders / authHeader;HTTP 自选Java SDK

简单说:

  • PHP / Node.js:封装最完整,getToken 开箱即用,业务调用一行完成整个信封处理。
  • Python:提供 auth_header(计算 auth + md5(APP-ID & secret))、build_requestverify_response 三件套,HTTP 请求自己发。
  • Go / Java:提供全部加解密、签名、canonical 串、nonce 生成与 AuthHeader 原语,HTTP 客户端与 JSON 库完全由你选择,适合接入已有服务框架。

getToken 的响应与其它接口一样是加密 + 签名信封,不是明文 token。无论用哪种语言,都必须验签 + 解密后再取 token 字段,详见获取 token

下载

SDK 打包为单个压缩包:

下载 merchant-api-v2.tar.gz

同目录提供校验文件 merchant-api-v2.tar.gz.sha256。下载后请先校验完整性,再解压使用:

bash
# 将 tar.gz 与 .sha256 下载到同一目录后执行:
sha256sum -c merchant-api-v2.tar.gz.sha256   # 输出 "merchant-api-v2.tar.gz: OK" 即通过
tar -xzf merchant-api-v2.tar.gz
bash
shasum -a 256 -c merchant-api-v2.tar.gz.sha256
tar -xzf merchant-api-v2.tar.gz

校验不通过(输出 FAILED)说明文件在传输中损坏或被篡改,请重新下载;仍失败请联系平台。

包内容清单

merchant-api-v2.tar.gz
├── README.md                        # 完整对接文档(协议规范、接口参考、错误排查)
└── sdk/
    ├── php/AnonyV2Client.php        # PHP SDK
    ├── python/anony_v2.py           # Python SDK
    ├── node/anony_v2.js             # Node.js SDK
    ├── go/anonyv2.go                # Go SDK
    ├── go/go.mod                    # Go module 定义
    └── java/AnonyV2Client.java      # Java SDK

包内不含任何密钥APP-ID、secret、平台公钥 public_t、商户私钥 private_u 需向平台获取 / 在商户后台查看,见密钥与凭据

密钥格式提醒:base64(PEM)

传给 SDK 的是 base64(PEM),不是原始 PEM

所有 SDK 的密钥入参格式均为 base64(PEM):即对标准 PEM 文本(-----BEGIN ... KEY----- 整段)再做一次 Base64。SDK 内部会先 Base64 解码还原 PEM,再加载密钥——不要自己提前解码,也不要直接传原始 PEM 文本。

  • 商户私钥 private_u:PKCS#8(BEGIN PRIVATE KEY
  • 平台公钥 public_t:SPKI(BEGIN PUBLIC KEY
  • 密钥均为 RSA-2048

格式细节与生成方法见密钥与凭据。私钥仅存于你的服务端,切勿写入前端、日志或第三方。

下一步

  1. 按语言进入对应 SDK 页跑通示例:PHP / Python / Node.js / Go / Java
  2. 用真实密钥调用上线自检 selfcheck,验证上行、下行链路均正确后,通知平台正式启用。
  3. 联调中遇到验签 / 解密失败,按排障指南的顺序检查(OAEP 是否 SHA-1、canonical 串、密钥角色、时间同步)。