Fetch the repository succeeded.
微信支付 API v3 官方Go语言客户端代码库。
版本号：v0.2.5
版本功能：
core.Client，该 HTTP Client 在执行请求时将自动携带身份认证信息，并检查应答的微信支付签名。core/downloader，提供手动下载器CertificateDownloader，以及自动下载管理器CertificateDownloaderMgrcore/notify，提供通知处理器Handler，可以对微信支付回调通知进行验签，然后对回调通知内容进行解密，并解析为特定的结构（如支付回调通知的Transaction），也可以选择解析为字典map[string]interface{}兼容性： 本版本为测试版本，因为接口重命名/代码结构调整等原因，与之前版本存在不兼容的情况。
为了向广大开发者提供更好的使用体验，微信支付诚挚邀请您将使用微信支付 API v3 SDK中的感受反馈给我们。 您的反馈将对我们改进SDK大有帮助，点击参与问卷调查
版本 v0.2.2 中我们包含了一个重大更新内容：将现有接口SDK中的整型参数统一为int64。
这一行为的目的是规范SDK中对整型参数的实现，避免因为未来可能的int32 -> int64的字段升级导致大规模兼容性问题。
此次升级会导致 payments 下4个API接口的SDK的兼容性问题，建议开发者以如下方式对自己的代码进行更新。
int64代码修复步骤go get -u github.com/wechatpay-apiv3/wechatpay-go@v0.2.5 升级依赖。go.mod 文件中依赖的 github.com/wechatpay-apiv3/wechatpay-go 至 v0.2.5版本。在项目根目录下执行go build ./...可以递归检查代码中的编译错误，即可快速定位到需要修改的代码。
对于请求 payments 接口的数据，可以在设置参数时使用int64(xxx)进行类型转换。当然也可以将请求链路上的类型从int32更新为int64。
req := jsapi.PrepayRequest{}
// 升级前
req.Amount = &jsapi.Amount{
Currency: core.String("CNY"),
Total: &totalInt32,
}
// 升级后
totalInt64 := int64(totalInt32)
req.Amount = &jsapi.Amount{
Currency: core.String("CNY"),
Total: &totalInt64,
}
对于应答结果的处理，我们不建议将返回结果中的int64强制类型转换为int32，而是建议将后续处理链路中的类型从int32更新为int64。
这样变更可能会更复杂，但是安全性更好，避免因为数据溢出导致错误。
// 升级前
func GetTransactionTotal(resp *payments.Transaction) int32 {
return *resp.Amount.Total
}
// 升级后
func GetTransactionTotal(resp *payments.Transaction) int64 {
return *resp.Amount.Total
}
如果你有针对 payments 编写测试用例，你可能需要对测试用例代码进行更新，并重新测试确保一切正常。
go.mod文件的话说明你的项目已经使用 Go Modules 进行管理）如果你的项目还不是使用 Go Modules 进行管理，在项目根目录下执行：
go mod init
在 go.mod 文件中加入对本SDK的依赖：
require (
github.com/wechatpay-apiv3/wechatpay-go v0.2.5
)
并使用go mod tidy进行下载。
也可以直接在项目目录中执行：
go get -u github.com/wechatpay-apiv3/wechatpay-go@v0.2.5
来自动完成go.mod的修改与SDK的下载。
为向微信支付 API 发送请求，需要初始化一个 core.Client 实例。
package main
import (
"context"
"crypto/rsa"
"log"
"net/http"
"github.com/wechatpay-apiv3/wechatpay-go/core"
"github.com/wechatpay-apiv3/wechatpay-go/core/option"
)
func main() {
// 示例参数，实际使用时请自行初始化
var (
mchID string // 商户号
mchCertificateSerialNumber string // 商户证书序列号
mchPrivateKey *rsa.PrivateKey // 商户私钥
mchAPIv3Key string // 商户APIv3密钥
customHTTPClient *http.Client // 可选，自定义客户端实例
)
ctx := context.Background()
opts := []core.ClientOption{
// 一次性设置 签名/验签/敏感字段加解密，并注册 平台证书下载器，自动定时获取最新的平台证书
option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
// 设置自定义 HTTPClient 实例，不设置时默认使用 http.Client{}，并设置超时时间为 30s
option.WithHTTPClient(customHTTPClient),
}
client, err := core.NewClient(ctx, opts...)
if err != nil {
log.Printf("new wechat pay client err:%s", err)
return
}
// 接下来使用 client 进行请求发送
_ = client
}
使用以上方法，可以快速构建一个集成了签名/验签的Client，除此以外，还会自动初始化全局默认的平台证书下载管理器downloader.MgrInstance()提供平台证书。
每24小时更新一次平台证书，保证验签所使用的证书更新。
如果你希望直接使用本地的平台证书，也可以使用如下初始化方法
func main() {
// 示例参数，实际使用时请自行初始化
var (
mchID string // 商户号
mchCertificateSerialNumber string // 商户证书序列号
mchPrivateKey *rsa.PrivateKey // 商户私钥
wechatPayCertList []*x509.Certificate // 平台证书列表
customHTTPClient *http.Client // 可选，自定义客户端实例
)
ctx := context.Background()
opts := []core.ClientOption{
// 一次性设置 签名/验签/敏感字段加解密，使用本地提供的平台证书列表
option.WithWechatPayAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, wechatPayCertList),
// 设置自定义 HTTPClient 实例，不设置时默认使用 http.Client{}，并设置超时时间为 30s
option.WithHTTPClient(customHTTPClient),
}
client, err := core.NewClient(ctx, opts...)
if err != nil {
log.Printf("new wechat pay client err:%s", err)
return
}
// 接下来使用 client 进行请求发送
_ = client
}
core.Client初始化完成后，可以在多个goroutine中并发使用。
AES-256-GCM加密时使用的对称加密密钥。为了方便开发者快速上手，我们给各服务分别生成了相应的示例代码api_xx_example_test.go。例如 JSAPI 支付的示例代码就位于services/payments/jsapi/api_jsapi_example_test.go。开发者可以按需查阅。
以下我们以常用的接口为例，说明如何使用服务接口 SDK。
import (
"log"
"github.com/wechatpay-apiv3/wechatpay-go/services/payments/jsapi"
)
func JsapiPrepay() error {
// 请自行初始化 client
var client *core.Client
svc := jsapi.JsapiApiService{Client: client}
// 得到prepay_id，以及调起支付所需的参数和签名
resp, result, err := svc.PrepayWithRequestPayment(ctx,
jsapi.PrepayRequest{
Appid: core.String("wxd678efh567hg6787"),
Mchid: core.String("1900009191"),
Description: core.String("Image形象店-深圳腾大-QQ公仔"),
OutTradeNo: core.String("1217752501201407033233368018"),
Attach: core.String("自定义数据说明"),
NotifyUrl: core.String("https://www.weixin.qq.com/wxpay/pay.php"),
Amount: &jsapi.Amount{
Total: core.Int32(100),
},
Payer: &jsapi.Payer{
Openid: core.String("oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"),
},
},
)
if err == nil {
log.Println(resp)
} else {
log.Println(err)
return err
}
}
import (
"log"
"github.com/wechatpay-apiv3/wechatpay-go/services/payments/jsapi"
)
func QueryOrder() error {
// 请自行初始化 client
var client *core.Client
svc := jsapi.JsapiApiService{Client: client}
resp, result, err := svc.QueryOrderById(ctx,
jsapi.QueryOrderByIdRequest{
TransactionId: core.String("4200000985202103031441826014"),
Mchid: core.String("1900009191"),
},
)
if err == nil {
log.Println(resp)
} else {
log.Println(err)
return err
}
}
import (
"os"
"github.com/wechatpay-apiv3/wechatpay-go/core"
"github.com/wechatpay-apiv3/wechatpay-go/core/consts"
"github.com/wechatpay-apiv3/wechatpay-go/services/fileuploader"
)
func UploadImage() error {
// 请自行初始化 client
var client *core.Client
file, err := os.Open("resource/demo.jpg")
defer file.Close()
if err != nil {
return err
}
svc := fileuploader.ImageUploader{Client: client}
resp, result, err := svc.Upload(ctx, file, "demo.jpg", consts.ImageJPG)
// 处理 resp
}
如果你需要使用的 SDK 尚未提供，你可以使用core.Client的GET、POST等方法发送 HTTP 请求，而不用关心签名验签等逻辑。
以 下载微信支付平台证书 为例：
var (
result *core.APIResult
err error
)
result, err = client.Get(ctx, "https://api.mch.weixin.qq.com/v3/certificates")
// 处理 result.Response
使用 core.Client 发送 HTTP 请求后会得到一个 core.APIResult 实例，其中包含了当次请求的请求报文 *http.Request 以及应答报文 *http.Response。
以下情况，SDK 发送请求会返回 error：
2xx HTTP 状态码为了方便使用，我们将服务器返回的 4xx 和 5xx 错误，转换成了APIError。开发者可以参考以下的代码进行错误处理。
result, err := client.Get(ctx, "https://api.mch.weixin.qq.com/v3/certificates")
if err != nil {
if core.IsAPIError(err, "INVALID_REQUEST") {
// 处理无效请求
}
// 处理的其他错误
}
github.com/wechatpay-apiv3/wechatpay-go
├── core // 本代码库核心功能
├── services // 微信支付各服务API对应的SDK，目前只包含部分API，更多服务跟进中
├── docs // 以上微信支付各服务API对应的SDK的说明文档
├── utils // 各种常用工具函数
└── README.md // 本文档
为了保证通信过程中敏感信息字段（如用户的住址、银行卡号、手机号码等）的机密性，微信支付 API v3 要求商户对上送的敏感信息字段进行加密。 与之相对应，微信支付会对下行的敏感信息字段进行加密，商户需解密后方能得到原文。 详见这里
工具包 github.com/wechatpay-apiv3/wechatpay-go/utils 中提供了加解密所需要的函数，可以使用这些方法手动对敏感信息字段进行加解密
package utils
// EncryptOAEPWithPublicKey 使用公钥进行加密
func EncryptOAEPWithPublicKey(message string, publicKey *rsa.PublicKey) (ciphertext string, err error)
// EncryptOAEPWithCertificate 先解析出证书中的公钥，然后使用公钥进行加密
func EncryptOAEPWithCertificate(message string, certificate *x509.Certificate) (ciphertext string, err error)
// DecryptOAEP 使用私钥进行解密
func DecryptOAEP(ciphertext string, privateKey *rsa.PrivateKey) (message string, err error)
如果你使用option.WithWechatPayAutoAuthCipher初始化core.Client，SDK 会自动在默认的证书下载管理器中注册对应商户的证书下载和自动更新任务。
它除了会为core.Client中的验签器提供平台证书外，你可以直接使用mgr.GetCertificate或mgr.GetCertificateVisitor等方法直接获取到证书，用于敏感字段的加密。
Wechatpay-Serial 请求头对请求参数进行加密后，需要在请求头中添加 Wechatpay-Serial 参数，用于传递加密所使用的微信支付平台证书序列号。
目前 core.Client 的 Get/Post/Put/Patch/Delete/Upload 方法只能传递最简单的内容，并不支持设置 HTTPHeader。
你可以使用 Request 方法来传输自定义 HTTPHeader。
目前我们已经完成了敏感字段自动加解密工具的开发，你可以使用WithWechatPayAuthCipher/WithWechatPayAutoAuthCipher/WithCipher等选项为
core.Client 设置加解密器。
但是比较遗憾的是，加解密器的正确运作依赖于我们在接口请求/应答结构所进行的Tag标记，也就是说只有我们提供了SDK的服务才能享受到自动加解密。
而目前我们所提供了SDK的服务接口均不存在需要加解密的字段，故而暂时这个能力还无法为大家提供服务。如果开发者需要访问存在敏感字段的接口，目前还是需要手动进行加解密。
我们会尽快上线更多服务接口的SDK，让自动加解密发挥它的价值。
core/notify 中提供了回调通知处理器 Handler，提供回调通知验签与解密功能。Handler 需要使用验签器 Verifier 和 商户APIv3密钥进行初始化。
mchAPIv3Key := "<your api v3 key>"
verifier := verifiers.NewSHA256WithRSAVerifier(core.NewCertificateMapWithList([]*x509.Certificate{wechatPayCert}))
handler := NewNotifyHandler(mchAPIv3Key, verifier)
初始化完成后即可调用handler.ParseNotifyRequest方法进行回调通知的验签及解密。
notify.Handler如果你已经知道如何在创建 client 的时候使用平台证书下载管理器自动更新平台证书，你可以在回调处理中也享受管理器提供了平台证书自动更新能力。
为了你能正确使用平台证书管理器，请确保你已经阅读并理解在更多地方使用平台证书下载管理器的说明。
以下是使用平台证书下载管理器初始化 notify.Handler 的示例代码
var (
mchID string // 商户号
mchCertificateSerialNumber string // 商户证书序列号
mchPrivateKey *rsa.PrivateKey // 商户私钥
mchAPIv3Key string // 商户APIv3密钥
)
func Example_a() {
ctx := context.Background()
client, err := core.NewClient(ctx, option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key))
if err != nil {
return
}
// 由于已经使用 WithWechatPayAutoAuthCipher 在 downloader.MgrInstance() 中注册了商户的下载器，则下面可以直接使用该下载管理器获取证书
certVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certVisitor))
}
func Example_b() {
// 这是一个单纯的回调处理进程，没有使用 WithWechatPayAutoAuthCipher 创建商户的 client，此时则需要手动注册下载器
ctx := context.Background()
err := downloader.MgrInstance().RegisterDownloaderWithPrivateKey(ctx, mchPrivateKey, mchCertificateSerialNumber, mchID, mchAPIV3Key)
if err != nil {
return
}
// 注册完成，使用下载管理器获取证书
certVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certVisitor))
}
当默认的本地签名和验签方式不适合你的系统时，你可以通过实现Signer或者Verifier来定制签名和验签。
比如，你可以把商户私钥集中存储，业务系统通过远程调用进行签名，你可以这样做。
// 签名器
type CustomSigner struct {
}
func (s *CustomSigner) Sign(ctx context.Context, message string) (*auth.SignatureResult, error) {
// TODO: 远程调用获取签名信息
return &auth.SignatureResult{MchID: "xxx", MchCertificateSerialNo: "xxx", Signature: "xxx"}, nil
}
// 校验器
type CustomVerifier struct {
}
func (v *CustomVerifier) Verify(ctx context.Context, serial, message, signature string) error {
// TODO: 远程调用验签
return nil
}
当你需要使用自定的签名器和校验器时，你可以这样来创建客户端
package core_test
import (
"context"
"path/to/your/custom_signer"
"path/to/your/custom_verifier"
"github.com/wechatpay-apiv3/wechatpay-go/core"
"github.com/wechatpay-apiv3/wechatpay-go/core/auth/credentials"
"github.com/wechatpay-apiv3/wechatpay-go/core/auth/validators"
"github.com/wechatpay-apiv3/wechatpay-go/core/option"
)
func NewCustomClient(ctx context.Context, mchID string) (*core.Client, error) {
signer := &custom_signer.CustomSigner{
// ...
}
verifier := &custom_verifier.CustomVerifier{
// ...
}
opts := []core.ClientOption{
option.WithSigner(signer),
option.WithVerifier(verifier),
}
return core.NewClient(ctx, opts...)
}
现在本 SDK 已经提供了命令行工具供开发者使用。
首先使用 go 指令下载命令行工具
go get -u github.com/wechatpay-apiv3/wechatpay-go/cmd/wechatpay_download_certs@v0.2.5
然后执行 wechatpay_download_certs 即可下载平台证书到当前目录
wechatpay_download_certs -m <mchID> -p <mchPrivateKeyPath> -s <mchSerialNo> -k <mchAPIv3Key>
完整参数列表可运行 wechatpay_download_certs -h 进行查看。
注意： 如果你想使用
downloader.MgrInstance().GetCertificate或downloader.MgrInstance().GetCertificateVisitor来获取某个商户mchID的平台证书（比如用于回调通知验签）， 请确保你在该进程中使用过option.WithWechatPayAutoAuthCipher创建该商户的client。 这是因为平台证书下载管理器必须使用商户信息注册下载器之后才能提供对应商户的平台证书。如果你并不需要创建该商户的 client，请使用
downloader.MgrInstance().RegisterDownloaderWithPrivateKey手动注册下载器。
option.WithWechatPayAutoAuthCipher和downloader.MgrInstance().RegisterDownloaderWithPrivateKey只需要在进程中调用过一次即可，多次调用无实际意义。 如果二者都没有调用过，则查询该商户的平台证书时结果均为空。
如果你希望了解更多，并自行对平台证书下载管理器的生命周期进行管理，可以自行阅读 core/downloader 的代码。
账单下载API 分成了两个步骤：
/v3/bill/tradebill 获取账单下载链接和账单摘要/v3/billdownload/file 账单文件下载，请求需签名但应答不签名其中第二步的应答中不包含应答数字签名，无法进行验签，应使用WithoutValidator()跳过应答签名的校验。
opts := []core.ClientOption{
option.WithMerchantCredential(mchID, mchCertificateSerialNumber, privateKey),
option.WithoutValidator(),
}
client, err := core.NewClient(ctx, opts...)
注意：第一步中应正常对应答签名进行验证
注意：开发者在下载文件之后，应使用第一步获取的账单摘要校验文件的完整性
不论是使用 Client 的 HTTP 方法（Get/Post/Put/Delete等）直接发送 HTTP 请求，还是使用服务API对应的SDK发起请求，均会返回 *core.APIResult 结构。
该结构中包含了本次发起 HTTP 请求的 http.Request 对象和微信支付应答的 http.Response 对象。
var (
request *http.Request
response *http.Response
)
result, err = client.Get(ctx, "")
request = result.Request
response = result.Response
请参考 aes.go 和 aes_test.go。
我们欢迎来自社区的开发者贡献你们的想法和代码。请你在提交 PR 之前，先提一个对应的 issue 说明以下内容：
#35 是一个很好的参考。
开发者提交的代码，应能通过我们所有的测试用例。
我们在单元测试中使用了gomonkey和require，测试前请确认相关的依赖。你可以使用以下命令获取所有的依赖。
go get -t -v
由于gomonkey的原因，在执行测试用例时需要携带参数-gcflags=all=-l。你可以使用以下命令发起测试。
go test -gcflags=all=-l ./...
如果你发现了BUG或者有任何疑问、建议，欢迎通过 issue 进行反馈
也欢迎访问我们的开发者社区
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手