{"id":20459739,"url":"https://github.com/rosbit/go-wxpay-gateway","last_synced_at":"2025-04-13T05:51:47.408Z","repository":{"id":57501668,"uuid":"189391093","full_name":"rosbit/go-wxpay-gateway","owner":"rosbit","description":"通用微信支付网关","archived":false,"fork":false,"pushed_at":"2024-11-21T02:01:27.000Z","size":282,"stargazers_count":16,"open_issues_count":0,"forks_count":8,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-26T22:36:12.966Z","etag":null,"topics":["gateway","go","golang","pay-gateway","weixin-pay","wxpay"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rosbit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-30T10:06:42.000Z","updated_at":"2024-11-21T02:01:31.000Z","dependencies_parsed_at":"2022-09-19T09:10:54.278Z","dependency_job_id":null,"html_url":"https://github.com/rosbit/go-wxpay-gateway","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosbit%2Fgo-wxpay-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosbit%2Fgo-wxpay-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosbit%2Fgo-wxpay-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosbit%2Fgo-wxpay-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rosbit","download_url":"https://codeload.github.com/rosbit/go-wxpay-gateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670505,"owners_count":21142901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gateway","go","golang","pay-gateway","weixin-pay","wxpay"],"created_at":"2024-11-15T12:17:08.251Z","updated_at":"2025-04-13T05:51:47.386Z","avatar_url":"https://github.com/rosbit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 通用微信支付网关服务\n\n 1. `go-wxpay-gateway`是封装了与微信支付的相关接口，以更简便易用的形式(封装了各种编码、加解密、证书、\n     随机数、沙箱的使用)让应用使用微信支付功能\n 1. `go-wxpay-gateway`运行后，通过HTTP给需要微信支付的应用提供接口，请求与响应的数据都是JSON，任何支持\n     HTTP的语言都可以实现业务代码。\n\n## 架构图\n\n ![架构图](wxpay-gateway.png)\n\n - 任何商户平台的配置信息都统一由`go-wxpay-gateway`集中管理，应用只要通过`应用名`、`appId`就可以使用这些参数\n - `go-wxpay-gateway`提供接口解析支付/退款通知程序接收的参数，并把解析后的结果、返回给微信支付的结果返回接口调用程序\n - 下单、支付、支付结果通知流程\n     1. `微信支付应用`准备好支付信息(订单号、支付金额)，根据应用类型选取相应的支付方式(JSAPI/H5/APP/NATIVE)，\n         同时把`应用名`、`appId`、`支付结果通知URL`提供给`go-wxpay-gateway`\n     1. `go-wxpay-gateway`取出`应用名`对应的配置信息，向`微信商户平台`发出统一支付接口调用\n     1. `微信商户平台`返回相应的支付参数\n     1. `go-wxpay-gateway`抽取支付相关的参数，**生成**或**包装**`激活微信支付`的参数，返回给`微信支付应用`\n     1. `微信支付应用`把相关参数返回给前端 或者 提供二维码 激活`微信app`\n     1. 用户通过`微信app`完成支付\n     1. `微信商户平台`异步把支付结果通知给`支付结果通知URL`，该URL由应用自己完成接收\n     1. `支付结果通知URL`处理程序把收到的信息和`应用名`转发给`go-wxpay-gateway`提供的参数解析接口\n     1. `go-wxpay-gateway`根据其中的`应用名`找到相应配置参数，对支付结果通知参数进行验证解析\n     1. `go-wxpay-gateway`把`结果通知`的解析结果、返回给微信支付的结果返回给接口调用程序\n\n## 下载、编译方法\n 1. 前提：已经安装go 1.11.x及以上、git、make\n 2. 进入任一文件夹，执行命令\n\n    ```bash\n    $ git clone https://github.com/rosbit/go-wxpay-gateway\n    $ cd go-wxpay-gateway\n    $ make\n    ```\n 3. 编译成功，会得到3个可执行程序\n     - `go-wxpay-gateway`: 微信支付网关程序，可以执行`./go-wxpay-gateway -v`显示程序信息。\n     - `go-wxpay-getsandbox`: 获取沙箱测试的apiKey工具，可以执行`./go-wxpay-getsandbox -v`显示程序信息。\n 4. Linux的二进制版本可以直接进入[releases](https://github.com/rosbit/go-wxpay-gateway/releases)下载\n\n## 运行方法\n### go-wxpay-gateway运行方法\n 1. 环境变量\n    - CONF_FILE: 指明配置的路径，格式见下文\n 1. 配置文件格式\n    - 是一个JSON\n    - 可以通过`wxpay-gateway.conf.sample.json`进行修改:\n    - 其中的`merchants`定义了商户的信息，实际账号和沙箱账号请分别配置\n    - 其中的`apps`定义了应用的信息，项`name`就是`应用名`\n         - `应用名`只要可以区分`微信支付应用`就可以了\n         - 如果使用沙箱测试，另外配置一个带`-dev`后缀的`应用名`，如`app-dev`，并指向沙箱merchant信息，\n           `微信支付应用`使用`app-dev`时不产生实际的费用；等测试成功后，再切换到实际的`应用名`，如`app`\n    - 配置项`endpoints`中的路由确保内网可以使用就可以了\n 1. 运行\n    - `$ CONF_FILE=./wxpay-gateway-conf.json ./go-wxpay-gateway`\n\n### go-wxpay-getsandbox运行方法\n - 运行`./go-wxpay-getsandbox \u003cappId\u003e \u003cmchId\u003e \u003cmchApiKey\u003e`\n     - 其中\u0026lt;appId\u0026gt;是指公众号、小程序、网页应用等id，请根据应用类型选用正确的appId\n     - \u0026lt;mchId\u0026gt;是指商户号，申请商户号的时可以拿到\n     - \u0026lt;mchApiKey\u0026gt;是商户号的apiKey，可以进入商户号管理界面设定\n - 运行成功后把沙箱mchApiKey输出到屏幕\n\n## go-wxpay-gateway服务的接口参数\n 1. 创建订单\n    - 对应配置项: `create-pay`\n    - 访问方法: POST\n    - URI: 如配置值为`/wxpay/create-pay`，则通过`/wxpay/create-pay/\u003ctype\u003e`访问，\u0026lt;type\u0026gt;的可取值为`JSAPI`、`H5`、`APP`、`NATIVE`\n    - **[注意]** 由于该接口会使用商户相关的配置信息，该接口不要暴露在外网，只要支付应用可以访问就可以了\n    - 以下为各种支付方式的参数、响应结果说明:\n       1. JSAPI支付\n           - URI: `/wxpay/create-pay/JSAPI`\n           - 请求参数\n\n              ```javascript\n              {\n                 \"appId\": \"公众号或小程序的appId\",\n                 \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n                 \"goods\": \"商品名\",\n                 \"udd\": \"用户自定义数据\",\n                 \"orderId\": \"支付应用中唯一的订单号\",\n                 \"fee\": 以分为单位的支付额度,\n                 \"ip\": \"创建订单的IP地址\",\n                 \"openId\": \"支付用户在公众号或小程序中的openId\",\n                 \"notifyUrl\": \"支付结果通知URL，必须外网可以访问\"\n              }\n              ```\n\n           - 响应结果\n\n             ```json\n             {\n                 \"code\": 200,\n                 \"msg\": \"OK\",\n                 \"result\":{\n                    \"jsapi_params\":{\n                       \"appId\": \"wxc914c55fba939e3c\",\n                       \"nonceStr\": \"Q6cU6oyVVvSsIWusb20dett1X59h4ezA\",\n                       \"package\": \"prepay_id=wx20190530150713356368\",\n                       \"paySign\": \"4F676F3FF2F4719289EA0685928CF83B\",\n                       \"signType\": \"MD5\",\n                       \"timeStamp\": \"1559200033\"\n                    },\n                    \"prepay_id\": \"wx20190530150713356368\"\n                  }\n             }\n             ```\n\n       1. H5支付\n           - URI: `/wxpay/create-pay/H5`\n           - 请求参数\n\n             ```json\n             {\n                 \"appId\": \"公众号或小程序的appId\",\n                 \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n                 \"goods\": \"商品名\",\n                 \"udd\": \"用户自定义数据\",\n                 \"orderId\": \"支付应用中唯一的订单号\",\n                 \"fee\": 以分为单位的支付额度,\n                 \"ip\": \"创建订单的IP地址\",\n                 \"redirectUrl\": \"在支付成功后需要跳转的URL\",\n                 \"notifyUrl\": \"支付结果通知URL，必须外网可以访问\"\n                 \"sceneInfo\": {\n                    \"h5_info\": {\n                      \"type\": \"类型\",\n                      \"wap_name\": \"wap应用名\",\n                      \"wap_url\": \"wap-site-url\"\n                    }\n                    // ---- OR ----\n                    \"h5_info\": {\n                      \"type\": \"类型\",\n                      \"app_name\":\"ios应用名\",\n                      \"bundle_id\": \"ios-bundle-id\"\n                    }\n                    // ---- OR ----\n                    \"h5_info\": {\n                      \"type\": \"类型\",\n                      \"app_name\":\"android应用名\",\n                      \"package_name\": \"android-package-name\"\n                    }\n                  }\n             }\n             ```\n\n           - 响应结果\n\n             ```json\n             {\n                  \"code\": 200,\n                  \"msg\": \"OK\",\n                  \"result\":{\n                      \"pay_url\": \"weixin://wxpay/s/An4baqw?redirect_url=http%3A%2F%2Flocalhost%3A11083\",\n                      \"prepay_id\": \"wx20190530150945625582\"\n                   }\n             }\n             ```\n\n       1. APP支付\n           - URI: `/wxpay/create-pay/APP`\n           - 请求参数\n\n             ```json\n             {\n                 \"appId\": \"公众号或小程序的appId\",\n                 \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n                 \"goods\": \"商品名\",\n                 \"udd\": \"用户自定义数据\",\n                 \"orderId\": \"支付应用中唯一的订单号\",\n                 \"fee\": 以分为单位的支付额度,\n                 \"ip\": \"创建订单的IP地址\",\n                 \"notifyUrl\": \"支付结果通知URL，必须外网可以访问\"\n             }\n             ```\n\n           - 响应结果\n\n             ```json\n             {\n                 \"code\": 200,\n                 \"msg\": \"OK\",\n                 \"result\":{\n                    \"prepay_id\": \"wx20190530151116852853\",\n                    \"req_params\":{\n                       \"appid\": \"wxc914c55fba939e3c\",\n                       \"noncestr\": \"iAQIoaqU854JHNnDhG00C0QSbTdIfthD\",\n                       \"package\": \"Sign=WXPay\",\n                       \"partnerid\": \"Iamyourpartner\",\n                       \"prepayid\": \"wx20190530151116852853\",\n                       \"sign\": \"1ADDF00C546912C446D9B9EA847B0D0F\",\n                       \"timestamp\": \"1559200276\"\n                    }\n                  }\n             }\n             ```\n\n       1. NATIVE支付\n           - URI: `/wxpay/create-pay/NATIVE`\n           - 请求参数\n\n              ```json\n              {\n                  \"appId\": \"公众号或小程序的appId\",\n                  \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n                  \"goods\": \"商品名\",\n                  \"udd\": \"用户自定义数据\",\n                  \"orderId\": \"支付应用中唯一的订单号\",\n                  \"fee\": 以分为单位的支付额度,\n                  \"ip\": \"创建订单的IP地址\",\n                  \"productId\": \"商品ID\",\n                  \"notifyUrl\": \"支付结果通知URL，必须外网可以访问\"\n               }\n               ```\n\n           - 响应结果\n\n               ```json\n               {\n                   \"code\": 200,\n                   \"msg\": \"OK\",\n                   \"result\":{\n                       \"code_url\": \"weixin://wxpay/s/An4baqw\",\n                       \"prepay_id\": \"wx20190530151411214102\"\n                    }\n               }\n               ```\n\n 1. 查询订单\n    - 对应配置项: `query-order`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/wxpay/query-order`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 请求参数\n\n      ```json\n      {\n          \"appId\": \"应用的appId\",\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n          \"orderId\": \"支付应用中的唯一订单id号\"\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"app_id\": \"wxc914c55fba939e3c\",\n          \"mch_id\": \"1530730681\",\n          \"device_info\": \"sandbox\",\n          \"result_code\": \"SUCCESS\",\n          \"err_code\": \"SUCCESS\",\n          \"err_code_des\": \"SUCCESS\",\n          \"open_id\": \"wxd930ea5d5a258f4f\",\n          \"is_subscribe\": true,\n          \"trade_type\": \"JSAPI\",\n          \"bank_type\": \"CMC\",\n          \"total_fee\": 101,\n          \"settlement_total_fee\": 101,\n          \"fee_type\": \"CNY\",\n          \"cash_fee\": 101,\n          \"cash_fee_type\": \"CNY\",\n          \"coupon_fee\": 0,\n          \"coupon_count\": 0,\n          \"coupons\": null,\n          \"transaction_id\": \"4662714807620190530105704209783\",\n          \"order_id\": \"o002\",\n          \"attach\": \"sandbox_attach\",\n          \"time_end\": \"20190530105704\"\n      }\n      ```\n\n 1. 关闭订单\n    - 对应配置项: `close-order`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/wxpay/close-order`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 请求参数\n\n      ```json\n      {\n          \"appId\": \"应用的appId\",\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n          \"orderId\": \"支付应用中的唯一订单id号\"\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"code\": 200,\n          \"msg\": \"OK\"\n      }\n      ```\n\n 1. 创建退款\n    - 对应配置项: `create-refund`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/wxpay/create-refund`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 请求参数\n\n      ```json\n      {\n          \"appId\": \"应用的appId\",\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n          \"orderId\": \"支付应用中的唯一订单id号\",\n          \"refundId\": \"支付应用中的唯一退款id号\",\n          \"totalFee\": 支付的总费用，单位分,\n          \"refundFee\": 退款的费用，单位分,\n          \"refundReason\": \"退款理由\",\n          \"notifyUrl\": \"支付结果通知URL，必须外网可以访问\"\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"code\": 200,\n          \"msg\": \"OK\",\n          \"result\":{\n            \"app_id\": \"wxc914c55fba939e3c\",\n            \"mch_id\": \"1530730681\",\n            \"result_code\": \"\",\n            \"err_code\": \"SUCCESS\",\n            \"err_code_des\": \"\",\n            \"transaction_id\": \"4630338607020190530111333587924\",\n            \"order_id\": \"o002\",\n            \"wx_refund_id\": \"4630338607020190530111333587\",\n            \"refund_id\": \"r002\",\n            \"total_fee\": 101,\n            \"settlement_total_fee\": 0,\n            \"refund_fee\": 101,\n            \"settlement_refund_fee\": 0,\n            \"fee_type\": \"CNY\",\n            \"cash_fee\": 101,\n            \"cash_fee_type\": \"CNY\",\n            \"cash_refund_fee\": 101,\n            \"coupon_refund_fee\": 0,\n            \"coupon_refund_count\": 0,\n            \"refund_coupons\": null\n          }\n      }\n      ```\n\n 1. 校验通知结果\n    - 校验支付支付结果\n       - URI: 对应配置文件里`endpoints`列表中的`verify-notify-pay` + '?app=\u003c应用名称\u003e'\n       - 方法: POST\n       - 请求参数: 应用支付结果URL收到的POST Body内容\n       - 响应结果:\n\n           ```json\n           {\n              \"code\": 200/406, // 正确返回200，失败返回406\n              \"msg\": \"OK/解析失败原因\",\n              \"params\": null, // code为406时返回\n              \"params\": {     // code为200时返回，是从Post Body中解析出来的\n                 \"result_code\": \"SUCCESS\",\n                 \"err_code\": \"SUCCESS\",\n                 \"err_code_des\": \"SUCCESS\",\n                 \"mch_id\": \"1530730681\",\n                 \"device_info\": \"APP\",\n                 \"trade_type\": \"APP\",\n                 \"attach\": \"any\",\n                 \"bank_type\": \"CMC\",\n                 \"fee_type\": \"CNY\",\n                 \"total_fee\": 101,\n                 \"settlement_total_fee\": 101,\n                 \"cash_fee_type\": \"CNY\",\n                 \"cash_fee\": 101,\n                 \"coupon_count\": 0,\n                 \"coupons\": null,\n                 \"is_subscribe\": true,\n                 \"open_id\": \"sandboxopenid\",\n                 \"order_id\": \"o003\",\n                 \"time_end\": \"20190530151118\",\n                 \"transaction_id\": \"4391741731420190530151118238943\"\n              },\n              \"msgForWxpay\": { // 返回给微信支付服务的内容，是一个XML\n                  \"\u003cxml\u003e....\u003c/xml\u003e\"\n              }\n           }\n           ```\n\n    - 校验退款结果\n       - URI: 对应配置文件里`endpoints`列表中的`verify-notify-refund` + '?app=\u003c应用名\u003e'\n       - 方法: POST\n       - 请求参数: 应用退款结果URL收到的POST Body内容\n       - 响应结果:\n           - 参考校验支付支付结果\n\n 1. V3版商家转账到零钱\n    - 对应配置项: `v3-transfer`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/v3/transfer`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 本接口只是“发出转账申请”，成功申请后需要在后台审核确认才能转出零钱\n    - 请求参数\n\n      ```json\n      {\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n          \"appId\": \"应用的appId\",\n          \"batchNo\": \"本次转账的批次，应用内唯一\",\n          \"batchName\": \"批次名称\",\n          \"batchRemark\": \"批次描述\",\n          \"details\": [\n             {\n               \"tradeNo\": \"批次内唯一交易id\",\n               \"amount\": 30, // 金额，单位\"分\",\n               \"desc\": \"描述\",\n               \"openId\": \"收款人在appId内的openId\",\n               \"userName\": \"2000以上，必须给收款人实名\"\n             },\n             {...}\n          ]\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"code\": 200,\n          \"msg\": \"OK\",\n          \"result\":{\n             \"wxBatchId\":\"1030000040101068797782022081801027450232\" // 微信批次id\n          }\n      }\n      ```\n\n 1. V3版商家批次查询\n    - 对应配置项: `v3-query-transfer`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/v3/query-transfer`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 请求参数\n\n      ```json\n      {\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n          \"status\": \"查询的状态值\",  //  \"ALL\" | \"SUCCESS\" | \"FAIL\", 不给用ALL\n          \"needDetail\": true, // 是否展示详情\n          \"wxBatchId\": \"转账申请成功返回的微信批次id\"\n             \"------ or -----\": \"或者\",\n          \"batchNo\": \"转账的批次，应用内唯一\"\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"code\": 200,\n          \"msg\": \"OK\",\n          \"result\":{\n             \"status\":\"FINISHED\",\n             \"total\": 1, // 数目\n             \"details\": [\n                {\n                   \"detail_id\":\"1040000040101068797782022081801020503999\", // 微信详情id\n                   \"out_detail_no\":\"tt202208170001\", // 对应自己的tradeNo\n                   \"detail_status\":\"SUCCESS\"         // 详情状态\n                }\n             ]\n          }\n      }\n      ```\n\n 1. V3版商家转账详情查询\n    - 对应配置项: `v3-query-transfer-detail`\n    - 访问方法: POST\n    - URI: 直接根据配置值访问，如`/v3/query-transfer-detail`\n    - **[注意]** 该接口配置成一个内网可以访问的API\n    - 请求参数\n\n      ```json\n      {\n          \"payApp\": \"go-wxpay-gateway配置文件中的应用名\",\n\n          \"wxBatchId\": \"转账申请成功返回的微信批次id\",\n          \"wxDetailId\": \"批次查询时返回的微信详情id\",\n             \"------ or -----\": \"或者\",\n          \"batchNo\": \"转账的批次，应用内唯一\",\n          \"tradeNo\": \"转账时详情的唯一id\"\n      }\n      ```\n\n    - 响应结果\n\n      ```json\n      {\n          \"code\": 200,\n          \"msg\": \"OK\",\n          \"result\":{\n              \"status\":\"SUCCESS\",  // 详情状态\n              \"amount\": 30, // 金额,单位分\n              \"remark\": \"转账时的备注\",\n              \"reason\": \"失败原因。如果成功，返回空\"\n          }\n      }\n      ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosbit%2Fgo-wxpay-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frosbit%2Fgo-wxpay-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosbit%2Fgo-wxpay-gateway/lists"}