微信小程序虚拟支付 Golang SDK
面向微信小程序虚拟支付的 Go SDK，覆盖核心支付链路、服务端接口、消息推送处理与未封装接口扩展。
--- ## 项目简介 `go-wxvirtualpay` 用于服务端对接微信小程序虚拟支付。 它覆盖的不只是几个 HTTP 接口，还包括接入时最容易反复出错和重复实现的部分： - 小程序支付参数构建 - 支付签名与用户态签名 - 代币、订单、资金、道具、广告金、投诉处理接口 - 推送验签、解析与响应构建 - 环境继承、错误处理、请求 Hook - 微信新增接口的业务侧快速扩展 ## 核心能力 - `BuildVirtualPaymentParams` 输出结构与 `wx.requestVirtualPayment` 对齐 - `CurrencyPay` 使用 `PayItems []api.CurrencyPayItem`，减少字符串硬编码 - 请求结构体中的 `Env` 不传时默认继承 `client.Config.Env` - 如需显式传入环境值，推荐使用 `client.Env()` - 支持全局 Hook 与单次请求 Hook，便于精细化调试和观测 - 支持 `MarshalBody`、`SignPay`、`SignUser`、`BuildSignedURL`、`DoCustomJSON` - 支持 XML / JSON 推送验签、解析和成功 / 失败响应构建 - 框架无关，可用于标准库、Gin、Echo、Chi、Fiber 等任意 HTTP 框架 ## 最小示例 ```go package main import ( "context" "fmt" "log" "gitee.com/ArtfulCoder/go-wxvirtualpay/api" "gitee.com/ArtfulCoder/go-wxvirtualpay/config" "gitee.com/ArtfulCoder/go-wxvirtualpay/logger" ) func main() { ctx := context.Background() cfg := config.NewConfig( config.WithAppID("wx1234567890"), config.WithOfferID("12345678"), config.WithAppKey("your_app_key"), config.WithEnv(config.EnvProduction), config.WithLogger(logger.NewConfigLoggerAdapter(logger.NewDefaultLogger())), ) client := api.NewClient(cfg) params, err := client.BuildVirtualPaymentParams(ctx, "session_key", &api.BuildVirtualPaymentParamsRequest{ Mode: "short_series_goods", OrderID: "order_123456", BuyQuantity: 1, GoodsID: "goods_001", GoodsPrice: 100, Attach: "custom_payload", }) if err != nil { log.Fatal(err) } payload, _ := params.ToJSON() fmt.Println(payload) } ``` ### 拉取说明 - 推荐使用 Gitee 仓库地址拉取：`go get gitee.com/ArtfulCoder/go-wxvirtualpay` - 正式项目建议按明确版本使用，例如：`go get gitee.com/ArtfulCoder/go-wxvirtualpay@v1.0.0` - `go get` 的版本解析以 tag 对应的提交为准；如果使用 `@v1.0.0`，实际拉取的是 `v1.0.0` tag 指向的代码 - `main` 分支适合作为稳定发布主线参考，但正式依赖管理更推荐以 tag 为准 ## Env 使用建议 - 大多数场景下，不需要在每个请求里重复传 `Env` - 如果请求结构体里的 `Env` 不传，SDK 会自动使用 `client` 配置中的环境值 - 如果你确实希望显式写出环境值，推荐使用 `client.Env()` ```go resp, err := client.QueryOrder(ctx, accessToken, &api.QueryOrderRequest{ OpenID: "user_openid", OrderID: "order_123", }) resp, err = client.QueryOrder(ctx, accessToken, &api.QueryOrderRequest{ OpenID: "user_openid", Env: client.Env(), OrderID: "order_123", }) ``` ## 功能覆盖 ### 代币管理 - `QueryUserBalance` - `CurrencyPay` - `CancelCurrencyPay` - `PresentCurrency` ### 订单管理 - `QueryOrder` - `NotifyProvideGoods` - `RefundOrder` ### 资金管理 - `QueryBizBalance` - `CreateWithdrawOrder` - `QueryWithdrawOrder` - `DownloadBill` ### 支付参数构建 - `BuildVirtualPaymentParams` ### 道具管理 - `StartUploadGoods` - `QueryUploadGoods` - `StartPublishGoods` - `QueryPublishGoods` ### 广告金与投诉处理 - `QueryTransferAccount` - `BindTransferAccout` - `CreateFundsBill` - `QueryFundsBill` - `QueryRecoverBill` - `QueryAdverFunds` - `DownloadAdverfundsOrder` - `GetComplaintList` - `GetComplaintDetail` - `GetNegotiationHistory` - `ResponseComplaint` - `CompleteComplaint` - `UploadVPFile` - `GetUploadFileSign` ## 未封装接口扩展 即使某个微信接口还没有被 SDK 正式封装，你也不需要在业务项目里重新实现签名、URL 拼接、Hook、超时控制和 HTTP 调用逻辑。 公开扩展能力包括： - `MarshalBody` - `SignPay` - `SignUser` - `BuildSignedURL` - `DoCustomJSON` ```go respBody, err := client.DoCustomJSON(ctx, &api.CustomJSONRequest{ Operation: "CustomAPI", URI: "/xpay/custom_api", AccessToken: accessToken, SessionKey: sessionKey, NeedPaySig: true, NeedUserSig: true, Body: map[string]interface{}{ "env": 0, "foo": "bar", }, }) _ = respBody _ = err ``` 适合的场景： - 微信新增接口还没进入 SDK - 业务项目要先行接入 - 内部灰度验证某个新接口 - 不想在业务代码里重复实现签名和请求治理逻辑 ## 当前能力边界 - 按当前已核对的微信小程序虚拟支付主文档，高频主路径接口已基本覆盖 - 当前暂未额外提供的主要是外围辅助能力，例如投诉图片下载辅助封装、广告金 / 投诉场景的更细粒度轮询辅助能力，以及后续官方新增接口的增量支持 ## 文档 - [快速开始](docs/quickstart.md) - [完整接入指南](docs/virtual-payment-guide.md) - [API 文档](docs/api.md) - [配置说明](docs/config.md) - [消息推送处理](docs/notify.md) - [使用示例](docs/examples.md) - [常见问题](docs/faq.md) - [更新日志](docs/changelog.md) - [项目设计](PROJECT_DESIGN.md) ## 开发 ### 运行测试 ```bash go test ./... ``` ### 代码检查 ```bash go vet ./... ``` ## 免责声明 - 本项目基于 MIT License 开源提供，按“现状”提供，不附带任何明示或暗示担保 - 使用者应自行评估其在生产环境、支付场景、合规要求和业务流程中的适用性 - 使用者应确保自身业务场景、产品内容、虚拟商品形态、营销方式和资金处理流程符合所在司法辖区的法律法规、行业监管要求以及微信平台规则 - 使用者应自行完成必要的法务、合规、财务、税务、隐私和数据安全审查，并对自身业务行为承担全部责任 - 微信官方接口、字段、策略和审核要求可能随时间变化，使用者应以微信官方最新文档和平台实际行为为准 - 对于涉及充值、扣费、退款、赠送、广告金、投诉处理等能力的具体使用方式，使用者应根据自身业务模型建立完整的风控、审计、对账、幂等和异常处理机制 - 因接入、配置、签名、业务处理、通知处理、退款处理或平台策略变化导致的直接或间接损失，项目维护者不承担责任 - 在生产环境使用前，建议先完成沙箱验证、真实业务回归和必要的安全审查 ## 许可证 本项目采用 MIT 许可证，见 `LICENSE`。 ## 作者与联系方式 - 作者：ArtfulCoder - Email：undefined788@qq.com - Gitee：