SDK 使用指南

更新时间：2026/9/16 11:08:10

概述

DaxPay 为开放支付 API（/unipay/*）提供官方签名 SDK，封装了请求签名、响应验签、回调验签与报文收发，免去手工实现签名机制的成本。Go / Java / Node.js / PHP / Python 五语言 SDK 共享同一套契约与黄金测试向量，行为字节级一致。

所有 SDK 只需配置两把钥匙：

钥匙	用途	来源
商户私钥（`privateKey`）	签名请求	商户生成 RSA 密钥对，私钥自己留存
平台公钥（`publicKey`）	验签响应与异步通知	管理端「应用配置」中获取

语言与仓库

语言	包坐标	环境要求	仓库
Go	`github.com/opendaxpay/dax-pay-sdk-go`	Go ≥ 1.21，零第三方依赖	Gitee / GitHub
Java	`cn.daxpay.open:daxpay-open-sdk`	Java ≥ 8（依赖 Hutool）	Gitee / GitHub
Node.js	`@daxpay/open-sdk`	Node ≥ 18（ESM + TypeScript）	Gitee / GitHub
PHP	`daxpay/open-sdk`	PHP ≥ 7.4（ext-json / openssl / mbstring）	Gitee / GitHub
Python	`daxpay-open-sdk`	Python ≥ 3.10（依赖 cryptography）	Gitee / GitHub

当前为源码引入

五个 SDK 均未发布到公共包仓库（Maven Central / npm / PyPI / Packagist），按下方各语言「安装」小节的源码引入方式使用。

快速开始

安装

bash

go get github.com/opendaxpay/dax-pay-sdk-go@main

import "github.com/opendaxpay/dax-pay-sdk-go/daxpay"

初始化客户端

config := daxpay.Config{
    ServiceUrl: "https://your-domain.com", // 平台网关地址
    MchNo:      "M200000001",              // 商户号
    AppId:      "APP001",                  // 应用 ID
    PrivateKey: merchantPrivateKeyPem,     // 商户私钥（PEM 文本）
    PublicKey:  platformPublicKeyPem,      // 平台公钥（PEM 文本）
    Timeout:    30 * time.Second,
}
client := daxpay.NewClient(config)

支付下单

result, err := client.Pay(context.Background(), &daxpay.PayParam{
    BizOrderNo: "PAY20260916001",
    Title:      "测试商品",
    Amount:     100, // 金额，单位分
    Method:     "wechat_qr",
    NotifyUrl:  "https://example.com/notify",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.OrderNo, result.PayBody)

PayResult 主要字段：orderNo（平台订单号）、tradeNo（交易号）、status（订单状态）、payBody（支付参数：二维码链接 / 调起参数 / 跳转 URL）、payBodyType（code_url / pay_info / redirect_url）。

回调验签

// rawBody 为异步通知的 HTTP 原始请求体（勿做任何反序列化预处理）
ok := client.VerifyNotice(rawBody)

通用请求（execute）

便捷方法当前覆盖支付下单；退款、退款同步、订单查询、关单等全部接口均可通过各 SDK 的通用 execute(path, param) 调用：path 为接口地址（如 /unipay/refund），param 为业务参数（mchNo/appId/sign/reqTime 等公共参数与签名由 SDK 自动填充），字段含义见各接口文档。

result, err := client.Execute(ctx, "/unipay/refund", map[string]any{
    "bizOrderNo": "PAY20260916001",
    "amount":     100,
    "reason":     "用户申请退款",
})

注意事项

密钥格式：各 SDK 接受 PEM 文本（Java/Go/Node/PHP/Python 一致）；Python 私钥为 PKCS#8、公钥为 X.509 SPKI 格式。
回调验签必须用原始请求体：verifyNotice 需要平台发来的原始报文字符串，先 JSON.parse 再序列化会导致字段顺序/空格变化而验签失败。
时间与金额：SDK 自动按平台规范生成 reqTime（北京时间 yyyy-MM-dd HH:mm:ss）；金额单位为分（Long/long）。
沙箱联调：serviceUrl 指向测试环境部署地址即可，SDK 行为与环境无关。

SDK 使用指南 ​

概述 ​

语言与仓库 ​

快速开始 ​

安装 ​

初始化客户端 ​

支付下单 ​

回调验签 ​

通用请求（execute） ​

注意事项 ​