diff --git a/README.md b/README.md index b3a2ef9..4d310d3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ -

最全最好用的微信支付V3 Spring Boot 组件

@@ -33,22 +32,26 @@ ## 简介 -Java微信支付V3支付Spring Boot Starter，支持微信优惠券，代金券、商家券、智慧商圈、商家转账到零钱、公众号支付、微信小程序支付、分账、支付分、商家券、合单支付、先享卡、电商收付通等全部微信支付功能API，同时满足多个服务商、多个商户开发需求。一键集成，屏蔽了复杂度，API友好，上手快，欢迎star。 +Java微信支付V3支付Spring Boot +Starter，支持微信优惠券，代金券、商家券、智慧商圈、商家转账到零钱、公众号支付、微信小程序支付、分账、支付分、商家券、合单支付、先享卡、电商收付通等全部微信支付功能API，同时满足多个服务商、多个商户开发需求。一键集成，屏蔽了复杂度，API友好，上手快，欢迎star。 ## Maven 最新中央仓库坐标 ```xml + cn.felord payment-spring-boot-starter 1.0.17.RELEASE ``` + ## JDK问题 **推荐使用Open JDK**，原因参见[FBI Warning](https://github.com/NotFound403/payment-spring-boot/issues/5) ## 文档地址 + - [payment-spring-boot GitHub文档](https://notfound403.github.io/payment-spring-boot) ## 目前已经实现所有服务商和直连商户接口 @@ -65,39 +68,27 @@ Java微信支付V3支付Spring Boot Starter，支持微信优惠券，代金券 更新日志参考[changelog](https://notfound403.github.io/payment-spring-boot/#/changelog) -## 核心API结构 -![](https://asset.felord.cn/blog/20220613092244.png) +## API清单 -- `WechatPartnerProfitsharingApi` 微信支付服务商V3分账 -- `WechatBrandProfitsharingApi` 微信支付服务商V3连锁品牌分账 -- `WechatPayCallback` 微信支付V3回调通知工具封装 -- `WechatAllocationApi` 微信支付V2分账（未来会移除） -- `WechatMarketingFavorApi` 微信支付代金券V3 -- `WechatCombinePayApi` 微信支付合单支付V3 -- `WechatPayScoreApi` 微信支付分V3 -- `WechatPayRedpackApi` 微信支付V2现金红包 -- `WechatDiscountCardApi` 微信支付V3先享卡 -- `WechatProfitsharingApi` 微信支付直连商户V3分账 -- `WechatPartnerPayApi` 微信支付服务商模式V3普通支付 -- `WechatMarketingBusiFavorApi` 微信支付V3商家券 -- `WechatPayTransfersApi` 微信支付V2企业付款到零钱，目前不包括到银行卡 -- `WechatDirectPayApi` 微信支付直连模式V3普通支付 -- `WechatPayScoreParkingApi` 微信支付分V3停车服务 -- `WechatBatchTransferApi` 微信支付V3批量转账到零钱 -- `WechatPartnerSpecialMchApi` 微信支付V3服务商商户进件 -- `WechatMediaApi` 微信支付V3媒体上传 -- `WechatEcommerceApi` 电商收付通 -- `WechatSmartGuideApi` 服务商或者直连商户-经营能力-支付即服务 -- `WechatGoldPlanApi` 服务商-经营能力-点金计划 +API结构如下： +![](https://asset.felord.cn/blog/20220613092244.png) +具体分为**直连商户**和**服务商**两个体系，请详细阅读文档说明 > 随着版本迭代功能会增加，可通过API注册表类`WechatPayV3Type`进行API接口检索。 ## 使用入门 + ### 集成配置 -关于集成配置请详细阅读[payment-spring-boot GitHub文档](https://notfound403.github.io/payment-spring-boot)中[快速接入](https://notfound403.github.io/payment-spring-boot/#/quick_start)章节 + +关于集成配置请详细阅读[payment-spring-boot GitHub文档](https://notfound403.github.io/payment-spring-boot) +中[快速接入](https://notfound403.github.io/payment-spring-boot/#/quick_start)章节 + ### 调用示例 + #### 开启支付 + 需要手动通过`@EnableMobilePay`注解开启支付 + ```java import cn.felord.payment.autoconfigure.EnableMobilePay; import org.springframework.context.annotation.Configuration; @@ -109,7 +100,9 @@ public class PayConfig { ``` #### 支付接口调用 + 这里简单以小程序支付为例，写了一个Spring MVC 控制器，在实践中建议对`WechatApiProvider`进行二次封装作服务层调用 + ```java import cn.felord.payment.wechat.enumeration.TradeBillType; import cn.felord.payment.wechat.v3.WechatApiProvider; @@ -135,6 +128,7 @@ public class PayController { @Autowired private WechatApiProvider wechatApiProvider; String TENANT_ID = "mobile"; + /** * 总流程建议为 生成商品订单 -> 生成对应的支付订单 -> 支付操作 -> 支付结果回调更新 -> 结束 *

@@ -213,7 +207,9 @@ public class PayController { } } ``` + #### 回调示例 + 回调可通过以下示例实现，多租户的回调可将租户ID`tenantId`作为路径参数来实现 ```java @@ -248,7 +244,7 @@ import java.util.stream.Collectors; * @author felord.cn * @since 1.0.0.RELEASE */ -@Profile({"wechat","dev"}) +@Profile({"wechat", "dev"}) @RestController @RequestMapping("/wxpay/callbacks") public class CallbackController { @@ -358,16 +354,17 @@ public class CallbackController { } ``` - - ## 开源协议 + **Apache 2.0** ## 仓库地址 + - [GitHub](https://github.com/NotFound403/payment-spring-boot) - [Gitee](https://gitee.com/felord/payment-spring-boot) ## QQ交流群 + 为了交流解惑，新建QQ群，可通过扫码进入。 ![QQ交流群](./docs/img/qqun.png) diff --git a/docs/wechat_v3_api.md b/docs/wechat_v3_api.md index da4b6e0..b4d44bc 100644 --- a/docs/wechat_v3_api.md +++ b/docs/wechat_v3_api.md @@ -1,112 +1,227 @@ ## 入口类 -`WechatApiProvider`是本项目微信支付的入口类，已被注入**Spring IoC**。它目前包含以下几个**API**（后续会增加）。 +`WechatApiProvider`是本项目微信支付的入口类，已被注入**Spring IoC**，由它来初始化微信支付相关的**API**，具体分为**直连商户 +**和**服务商**两个体系。 -### 代金券API +> 以下清单请搭配微信支付文档使用。 -`WechatMarketingFavorApi`是微信支付营销工具-[代金券相关API](https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/pages/convention.shtml)的封装。 +### 直连商户 -#### 创建代金券批次API +#### 基础支付 -`WechatResponseEntity createStock(StocksCreateParams params)` +- [x] `WechatDirectPayApi` 基础支付，通过`WechatApiProvider#directPayApi`初始化 + - [x] `jsPay` APP下单 + - [x] `appPay` JSAPI/小程序下单 + - [x] `h5Pay` H5下单 + - [x] `nativePay` Native下单 + - [x] 查询订单 + 1. `queryTransactionById` 微信支付订单号查询 + 2. `queryTransactionByOutTradeNo` 商户订单号查询 + - [x] `close` 关闭订单 + - [x] `WechatPayCallback#transactionCallback` 支付通知，参见下面回调说明 + - [x] `refund` 申请退款 + - [x] `queryRefundInfo` 查询单笔退款 + - [x] `WechatPayCallback#refundCallback` 退款结果通知，参见下面回调说明 + - [x] `downloadTradeBill` 申请交易账单，直接下载为gzip或者txt文件 + - [x] `downloadFundFlowBill` 申请资金账单，直接下载为gzip或者txt文件 +- [x] `WechatCombinePayApi` 合单支付，通过`WechatApiProvider#combinePayApi`初始化 + - [x] `jsPay` 合单APP下单 + - [x] `appPay` 合单JSAPI/小程序下单 + - [x] `h5Pay` 合单H5下单 + - [x] `nativePay` 合单Native下单 + - [x] `queryTransactionByOutTradeNo` 查询订单，**合单支付目前只支持商户订单号查询** + - [x] `close` 合单关闭订单 + - [x] `WechatPayCallback#combineTransactionCallback` 合单支付通知，参见下面回调说明 + - [x] `refund` 合单申请退款 + - [x] `queryRefundInfo` 合单查询单笔退款 + - [x] `WechatPayCallback#refundCallback` 退款结果通知，参见下面回调说明 + - [x] `downloadTradeBill` 申请交易账单，直接下载为gzip或者txt文件 + - [x] `downloadFundFlowBill` 申请资金账单，直接下载为gzip或者txt文件 +- [ ] ~~付款码支付~~，暂时没有V3接口，可通过payment spring boot 提供的V2扩展功能自行实现。 -#### 激活代金券批次API +#### 经营能力 - `WechatResponseEntity startStock(String stockId)` +##### 微信支付分 -#### 发放代金券API +- [x] `WechatPayScoreApi` 微信支付分，通过`WechatApiProvider#payScoreApi`初始化 + - [x] 公共API + - [x] `createServiceOrder` 创建支付分订单 + - [x] `queryServiceOrder` 查询支付分订单 + - [x] `cancelServiceOrder` 取消支付分订单 + - [x] `modifyServiceOrder` 修改订单金额 + - [x] `completeServiceOrder` 完结支付分订单 + - [x] `syncServiceOrder` 同步服务订单信息 + - [x] `WechatPayCallback#payscoreUserOrderCallback` 支付成功回调通知，参见下面回调说明 + - [x] `refund` 支付分申请退款 + - [x] `queryRefundInfo` 支付分查询单笔退款 + - [x] `WechatPayCallback#refundCallback` 支付分退款结果通知，参见下面回调说明 + - [x] 免确认预授权模式 + - [x] `permissions` 商户预授权 + - [x] `queryPermissionsByAuthCode` 查询与用户授权记录（授权协议号） + - [x] `terminatePermissionsByAuthCode` 解除用户授权关系（授权协议号） + - [x] `queryPermissionsByOpenId` 查询与用户授权记录（openid） + - [x] `terminatePermissionsByOpenId` 解除用户授权关系（openid） + - [x] `WechatPayCallback#permissionCallback` 开启/解除授权服务回调通知，参见下面回调说明 + - [x] 需确认模式 + - [x] `WechatPayCallback#payscoreUserOrderCallback` 确认订单回调通知，参见下面回调说明 -`WechatResponseEntity sendStock(StocksSendParams params)` +##### 支付即服务 -#### 暂停代金券批次API +- [x] `WechatSmartGuideApi` 支付即服务，通过`WechatApiProvider#smartGuideApi`初始化 + - [x] `register` 服务人员注册 + - [x] `assign` 服务人员分配 + - [x] `query` 服务人员查询 + - [x] `modify` 服务人员信息更新 -`WechatResponseEntity pauseStock(String stockId)` +#### 行业方案 -#### 重启代金券批次API +##### 智慧商圈 -`WechatResponseEntity restartStock(String stockId)` +- [x] `WechatBusinessCircleApi` 智慧商圈，通过`WechatApiProvider#businessCircleApi`初始化 + - [ ] 商圈会员积分服务授权结果通知回调（未实现） + - [x] `WechatPayCallback#mallTransactionCallback` 商圈会员场内支付结果通知，参见下面回调说明 + - [x] `apply` 商圈积分同步 + - [x] `WechatPayCallback#mallRefundCallback` 商圈会员场内退款通知，参见下面回调说明 + - [x] `queryAuthStatus` 商圈积分授权查询 + - [ ] 商圈会员待积分状态查询（未实现） + - [ ] 商圈会员停车状态同步（未实现） -#### 条件查询批次列表API -通过此接口可查询多个批次的信息，包括批次的配置信息以及批次概况数据。 +##### 微信支付分停车服务 -`WechatResponseEntity queryStocksByMch(StocksQueryParams params)` +- [x] `WechatPayScoreParkingApi` 微信支付分停车服务，通过`WechatApiProvider#payScoreParkingApi`初始化 + - [x] `find` 查询车牌服务开通信息 + - [x] `parking` 创建停车入场 + - [x] `transactionsParking` 扣费受理 + - [x] `queryTransactionByOutTradeNo` 查询订单 + - [x] `WechatPayCallback#payscoreParkingCallback` 停车入场状态变更通知，参见下面回调说明 + - [x] `WechatPayCallback#payscoreTransParkingCallback` 订单支付结果通知，参见下面回调说明 + - [x] `refund` 申请退款 + - [x] `queryRefundInfo` 查询单笔退款 + - [x] `WechatPayCallback#refundCallback` 退款结果通知，参见下面回调说明 -#### 查询批次详情API +#### 营销工具 -`WechatResponseEntity queryStockDetail(String stockId)` +##### 代金券 -#### 查询代金券详情API +- [x] `WechatMarketingFavorApi` 代金券，通过`WechatApiProvider#payScoreParkingApi`初始化 + - [x] `createStock` 创建代金券批次 + - [x] `startStock` 激活代金券批次 + - [x] `sendStock` 发放代金券 + - [x] `pauseStock` 暂停代金券批次 + - [x] `restartStock` 重启代金券批次 + - [x] `queryStocksByMch` 条件查询批次列表 + - [x] `queryStockDetail` 查询批次详情 + - [x] `queryCouponDetails` 查询代金券详情 + - [x] `queryMerchantsByStockId` 查询代金券可用商户 + - [x] `queryStockItems` 查询代金券可用单品 + - [x] `queryUserCouponsByMchId` 根据商户号查用户的券 + - [x] `downloadStockUseFlow` 下载批次核销明细 + - [x] `downloadStockRefundFlow` 下载批次退款明细 + - [x] `setMarketingFavorCallback` 设置消息通知地址 + - [x] `WechatPayCallback#couponCallback` 核销事件回调通知，参见下面回调说明 + - [x] `sendCouponsCard` 发放消费卡 -`WechatResponseEntity queryCouponDetails(CouponDetailsQueryParams params)` +> `sendCouponsCard` 发放消费卡，功能仅向指定邀约商户开放，如有需要请联系微信支付运营经理。 -#### 查询代金券可用商户API +##### 商家券 -`WechatResponseEntity queryMerchantsByStockId(StocksQueryParams params)` +- [x] `WechatMarketingBusiFavorApi` 商家券，通过`WechatApiProvider#busiFavorApi`初始化 + - [x] `createStock` 创建商家券券批次 + - [x] `queryStockDetail` 查询商家券详情 + - [x] `use` 核销用户券 + - [x] `queryUserStocks` 根据过滤条件查询用户券 + - [x] `queryUserCoupon` 查询用户单张券详情 + - [x] `uploadCouponCodes` 上传预存code + - [x] `setCallbacks` 设置商家券事件通知地址 + - [x] `getCallbacks` 查询商家券事件通知地址 + - [x] `associate` 关联订单信息 + - [x] `disassociate` 取消关联订单信息 + - [x] `budget` 修改批次预算 + - [x] `updateStock` 修改商家券基本信息 + - [x] `refund` 申请退券 + - [x] `deactivate` 使券失效 + - [x] `payMakeup` 营销补差付款 + - [x] `queryMakeup` 查询营销补差付款单详情 + - [x] `payMakeup` 营销补差付款 + - [x] `WechatPayCallback#busiFavorReceiveCallback` 领券事件回调通知，参见下面回调说明 -#### 查询代金券可用单品API +##### 委托营销 -`WechatResponseEntity queryStockItems(StocksQueryParams params)` +- [x] `WechatMarketingPartnershipApi` 委托营销，通过`WechatApiProvider#marketingshipApi`初始化 + - [x] `build` 建立合作关系 + - [x] `query` 查询合作关系列表 -#### 根据商户号查用户的券API +##### 支付有礼 -`WechatResponseEntity queryUserCouponsByMchId(UserCouponsQueryParams params)` +- [ ] 功能实现中…… -#### 下载批次核销明细API +##### 图片上传（营销专用） -`WechatResponseEntity downloadStockUseFlow(String stockId)` +- [x] 参见 **其它能力** -#### 下载批次退款明细API +##### 现金红包（基于V2） -`WechatResponseEntity downloadStockRefundFlow(String stockId)` +- [x] `WechatPayRedpackApi` 现金红包，通过`WechatApiProvider#redpackApi`初始化 + - [x] `sendRedpack` 发放随机红包 + - [x] `sendRedpack` 发放裂变红包 + - [x] `redpackInfo` 查询红包信息 -#### 营销图片上传API +> 重要：**基于V2实现，因此需要在配置文件中配置v2支付对应的`appSecret`参数** -`WechatResponseEntity marketingImageUpload(MultipartFile file)` +#### 资金应用 -#### 代金券核销回调通知API +##### 商家转账到零钱 -`WechatResponseEntity setMarketingFavorCallback(String notifyUrl)` +- [x] `WechatBatchTransferApi` 商家转账到零钱，通过`WechatApiProvider#batchTransferApi`初始化 + - [x] `batchTransfer` 发起批量转账 + - [x] 查询转账批次单 + 1. `queryBatchByBatchId` 通过微信批次单号查询批次单 + 2. `queryBatchByOutBatchNo` 通过商家批次单号查询批次单 + - [x] 查询转账明细单 + 1. `queryBatchDetailByWechat` 通过微信明细单号查询明细单 + 2. `queryBatchDetailByMch` 通过商家明细单号查询明细单 + - [x] 申请转账电子回单 + 1. `receiptBill` 转账账单电子回单申请受理接口 + 2. `downloadBill` 查询转账账单电子回单接口，附带下载能力 + - [x] 申请转账明细电子回单 + 1. `transferElectronic` 受理转账明细电子回单 + 2. `queryTransferElectronicResult` 查询转账账单电子回单接口 + - [x] 申请转账电子回单 + 1. `` 转账账单电子回单申请受理接口 + 2. `` 查询转账账单电子回单接口 -### 普通支付-直连模式API +##### 分账 -`WechatDirectPayApi`是微信基础支付工具-[普通支付-直连模式API](https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/pages/transactions.shtml)的封装。 +- [x] `WechatProfitsharingApi` 分账，通过`WechatApiProvider#profitsharingApi`初始化 + - [x] `profitsharingOrders` 请求分账 + - [x] `queryProfitsharingOrder` 查询分账结果 + - [x] `returnOrders` 请求分账回退 + - [x] `queryReturnOrders` 查询分账回退结果 + - [x] `unfreeze` 解冻剩余资金 + - [x] `queryAmounts` 查询剩余待分金额 + - [x] `addReceivers` 添加分账接收方 + - [x] `deleteReceivers` 删除分账接收方 + - [x] `downloadMerchantBills` 申请分账账单 -#### APP下单API +#### 风险合规 -`WechatResponseEntity appPay(PayParams payParams)` +##### 消费者投诉2.0 -#### JSAPI/小程序下单API +- [ ] 功能实现中…… -`WechatResponseEntity jsPay(PayParams payParams)` +#### 其它能力 -#### Native下单API +##### 清关报关 -`WechatResponseEntity nativePay(PayParams payParams)` +- [ ] 清关报关 暂时没有V3接口，可通过payment spring boot 提供的V2扩展功能自行实现。 -#### H5下单API +##### 媒体上传 -`WechatResponseEntity h5Pay(PayParams payParams)` +> 包含图片上传和视频上传 -#### 微信支付订单号查询API +- [x] `WechatMediaApi` 媒体上传，通过`WechatApiProvider#mediaApi`初始化 + - [x] `mediaImageUpload` 图片上传 + - [x] `mediaVideoUpload` 视频上传 + - [x] `marketingImageUpload` 营销图片上传 -`WechatResponseEntity queryTransactionById(TransactionQueryParams params)` - -#### 商户订单号查询API - -`WechatResponseEntity queryTransactionByOutTradeNo(TransactionQueryParams params)` - -#### 关单API - -`WechatResponseEntity close(String outTradeNo)` - -### 回调API - -所有需要回调处理的微信支付业务通过`WechatPayCallback`来进行处理。 - -#### 微信支付代金券核销回调API - -`Map couponCallback(ResponseSignVerifyParams params, Consumer couponConsumeDataConsumer)` - -#### 微信支付普通支付回调API - -`Map transactionCallback(ResponseSignVerifyParams params, Consumer couponConsumeDataConsumer)` \ No newline at end of file +> 通过营销**图片上传API**上传图片后可获得图片url地址。图片url可在微信支付营销相关的API使用，包括商家券、代金券、支付有礼等。 \ No newline at end of file diff --git a/payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/WechatBatchTransferApi.java b/payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/WechatBatchTransferApi.java index 627cd6d..51d3a93 100644 --- a/payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/WechatBatchTransferApi.java +++ b/payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/WechatBatchTransferApi.java @@ -103,7 +103,7 @@ public class WechatBatchTransferApi extends AbstractApi { } /** - * 微信批次单号查询批次单API + * 通过微信批次单号查询批次单API * * @param queryBatchTransferParams the queryBatchTransferParams * @return the wechat response entity @@ -132,33 +132,7 @@ public class WechatBatchTransferApi extends AbstractApi { } /** - * 微信明细单号查询明细单API - * - * @param queryBatchTransferDetailParams the queryBatchTransferDetailParams - * @return the wechat response entity - * @since 1.0.6.RELEASE - */ - public WechatResponseEntity queryBatchDetailByWechat(QueryBatchTransferDetailParams queryBatchTransferDetailParams) { - WechatResponseEntity wechatResponseEntity = new WechatResponseEntity<>(); - this.client().withType(WechatPayV3Type.BATCH_TRANSFER_DETAIL_WECHAT, queryBatchTransferDetailParams) - .function((type, params) -> { - Map pathParams = new HashMap<>(2); - pathParams.put("batch_id", params.getBatchIdOrOutBatchNo()); - pathParams.put("detail_id", params.getDetailIdOrOutDetailNo()); - - URI uri = UriComponentsBuilder.fromHttpUrl(type.uri(WeChatServer.CHINA)) - .build() - .expand(pathParams) - .toUri(); - return Get(uri); - }) - .consumer(wechatResponseEntity::convert) - .request(); - return wechatResponseEntity; - } - - /** - * 微信批次单号查询批次单API + * 通过商家批次单号查询批次单API * * @param queryBatchTransferParams the queryBatchTransferParams * @return the wechat response entity @@ -187,7 +161,33 @@ public class WechatBatchTransferApi extends AbstractApi { } /** - * 商家明细单号查询明细单API + * 通过微信明细单号查询明细单API + * + * @param queryBatchTransferDetailParams the queryBatchTransferDetailParams + * @return the wechat response entity + * @since 1.0.6.RELEASE + */ + public WechatResponseEntity queryBatchDetailByWechat(QueryBatchTransferDetailParams queryBatchTransferDetailParams) { + WechatResponseEntity wechatResponseEntity = new WechatResponseEntity<>(); + this.client().withType(WechatPayV3Type.BATCH_TRANSFER_DETAIL_WECHAT, queryBatchTransferDetailParams) + .function((type, params) -> { + Map pathParams = new HashMap<>(2); + pathParams.put("batch_id", params.getBatchIdOrOutBatchNo()); + pathParams.put("detail_id", params.getDetailIdOrOutDetailNo()); + + URI uri = UriComponentsBuilder.fromHttpUrl(type.uri(WeChatServer.CHINA)) + .build() + .expand(pathParams) + .toUri(); + return Get(uri); + }) + .consumer(wechatResponseEntity::convert) + .request(); + return wechatResponseEntity; + } + + /** + * 通过商家明细单号查询明细单API * * @param queryBatchTransferDetailParams the queryBatchTransferDetailParams * @return the wechat response entity @@ -260,7 +260,7 @@ public class WechatBatchTransferApi extends AbstractApi { } /** - * 转账明细电子回单受理API + * 受理转账明细电子回单API *

* 受理转账明细电子回单接口，商户通过该接口可以申请受理转账明细单电子回单服务。 *