cn.felord.payment.wechat.v3.api.direct

接口 MarketingBusiFavorApi

public interface MarketingBusiFavorApi

微信支付商家券

从以下版本开始:

2023 /8/22

作者:

dax

方法概要

限定符和类型	方法和说明
AssociateTime	associate(FavorAssociateInfo associateInfo) 商家券关联订单信息API 将有效态（未核销）的商家券与订单信息关联，用于后续参与摇奖以及返佣激励等操作的统计。
FavorBudgetResponse	budget(String stockId, FavorBudgetParams params) 修改批次预算API 商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量
StockResponse	createStock(FavorCreateParams params) 创建商家券券批次API 商家券介绍详见 微信支付商家券
GenericPayResponse<OffsetDateTime>	deactivate(FavorDeactivateParams params) 使券失效API 前置条件：券的状态为CouponState.SENDED 商户可以通过该接口将可用券进行失效处理，券被失效后无法再被核销
AssociateTime	disassociate(FavorAssociateInfo associateInfo) 商家券取消关联订单信息API 取消商家券与订单信息的关联关系。
FavorCallbackSetting	getCallbacks() 查询调用方商家券事件通知地址API
FavorCallbackSetting	getCallbacks(String mchId) 获取商家券事件通知地址API 通过调用此接口可查询设置的通知URL。
FavorSubsidyListResponse	payMakeup(FavorSubsidyParams params) 营销补差付款API 该API主要用于商户营销补贴场景， 支持基于单张券进行不同商户账户间的资金补差， 从而提升财务结算、资金利用效率。
FavorSubsidyResponse	queryMakeup(String subsidyReceiptId) 查询营销补差付款单详情API 查询商家券营销补差付款单详情
StockDetailResponse	queryStockDetail(String stockId) 查询商家券批次详情API 商户可通过该接口查询已创建的商家券批次详情信息。
UserCouponResponse	queryUserCoupon(String openid, String couponCode, String appid) 查询用户券详情API 服务商可通过该接口查询微信用户卡包中某一张商家券的详情信息。
UserCouponsDetailResponse	queryUserStocks(String openid, UserFavorQueryParams params) 根据过滤条件查询用户券API 商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。
GenericPayResponse<OffsetDateTime>	refund(FavorRefundParams params) 申请退券API 商户可以通过该接口为已核销的券申请退券
FavorReturnSubsidyResponse	returnReceipts(FavorSubsidyReturnParams params) 营销补差回退API 商户通过该接口可回退补差款
FavorCallbackSetting	setCallbacks(FavorCallbackSetting setting) 设置商家券事件通知地址API 用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。
cn.felord.retrofit.VoidResponse	updateStock(String stockId, FavorUpdateParams params) 修改商家券基本信息API 商户可以通过该接口修改商家券基本信息，已创建商家券批次，且修改时间位于有效期结束时间前
CodeUploadResponse	uploadCouponCodes(CouponCodeUploadParams params) 上传预存code API 商家券的Code码可由微信后台随机分配，同时支持商户自定义。
FavorUseResponse	use(FavorUseParams params) 核销用户券API 在用户满足优惠门槛后，服务商可通过该接口核销用户微信卡包中具体某一张商家券。

方法详细资料

createStock

@POST(value="v3/marketing/busifavor/stocks")
StockResponse createStock(@Body
                                                                        FavorCreateParams params)
                                                                 throws PayException

创建商家券券批次API

商家券介绍详见 微信支付商家券

参数:

params - the params

返回:

the wechat response entity

抛出:

PayException - the pay exception

queryStockDetail

@GET(value="v3/marketing/busifavor/stocks/{stock_id}")
StockDetailResponse queryStockDetail(@Path(value="stock_id")
                                                                                             String stockId)
                                                                                      throws PayException

查询商家券批次详情API

商户可通过该接口查询已创建的商家券批次详情信息。

参数:

stockId - the stock id

返回:

the wechat response entity

抛出:

PayException - the pay exception

use

@POST(value="v3/marketing/busifavor/coupons/use")
FavorUseResponse use(@Body
                                                                        FavorUseParams params)
                                                                 throws PayException

核销用户券API

在用户满足优惠门槛后，服务商可通过该接口核销用户微信卡包中具体某一张商家券。

参数:

params - the params

返回:

the wechat response entity

抛出:

PayException - the pay exception

queryUserStocks

@GET(value="v3/marketing/busifavor/users/{openid}/coupons")
UserCouponsDetailResponse queryUserStocks(@Path(value="openid")
                                                                                                       String openid,
                                                                                                       @QueryMap
                                                                                                       UserFavorQueryParams params)
                                                                                                throws PayException

根据过滤条件查询用户券API

商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。

参数:

openid - the openid

params - the params

返回:

the user coupon detail response

抛出:

PayException - the pay exception

queryUserCoupon

@GET(value="v3/marketing/busifavor/users/{openid}/coupons/{coupon_code}/appids/{appid}")
UserCouponResponse queryUserCoupon(@Path(value="openid")
                                                                                                                             String openid,
                                                                                                                             @Path(value="coupon_code")
                                                                                                                             String couponCode,
                                                                                                                             @Path(value="appid")
                                                                                                                             String appid)
                                                                                                                      throws PayException

查询用户券详情API

服务商可通过该接口查询微信用户卡包中某一张商家券的详情信息。

参数:

openid - the openid

couponCode - the coupon code

appid - the appid

返回:

the wechat response entity

抛出:

PayException - the pay exception

uploadCouponCodes

@POST(value="v3/marketing/busifavor/stocks/{stock_id}/couponcodes")
CodeUploadResponse uploadCouponCodes(@Body
                                                                                                          CouponCodeUploadParams params)
                                                                                                   throws PayException

上传预存code API

商家券的Code码可由微信后台随机分配，同时支持商户自定义。 如商家已有自己的优惠券系统，可直接使用自定义模式。 即商家预先向微信支付上传券Code，当券在发放时，微信支付自动从已导入的Code中随机取值（不能指定），派发给用户。

参数:

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

setCallbacks

@POST(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting setCallbacks(@Body
                                                                                   FavorCallbackSetting setting)
                                                                            throws PayException

设置商家券事件通知地址API

用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。 需要设置接收通知的URL，并在商户平台开通 营销事件推送 的能力，即可接收到相关通知。

营销事件推送：点击开通产品权限。由商家券批次创建方登录Pay平台，操作开通

注意：

• 仅可以收到由商户自己创建的批次相关的通知
• 需要设置apiv3秘钥，否则无法收到回调。
• 如果需要领券回调中的参数openid。需要创券时候传入 notify_appid参数。

参数:

setting - the setting

返回:

callbacks callbacks

抛出:

PayException - the pay exception

getCallbacks

@GET(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting getCallbacks(@Query(value="mchid")
                                                                                  String mchId)
                                                                           throws PayException

获取商家券事件通知地址API

通过调用此接口可查询设置的通知URL。

注意：

• 仅可以查询由请求商户号设置的商家券通知url

参数:

mchId - the mch id

返回:

callbacks callbacks

抛出:

PayException - the pay exception

getCallbacks

@GET(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting getCallbacks()
                                                                           throws PayException

查询调用方商家券事件通知地址API

返回:

the callbacks

抛出:

PayException - the pay exception

associate

@POST(value="v3/marketing/busifavor/coupons/associate")
AssociateTime associate(@Body
                                                                                 FavorAssociateInfo associateInfo)
                                                                          throws PayException

商家券关联订单信息API

将有效态（未核销）的商家券与订单信息关联，用于后续参与摇奖以及返佣激励等操作的统计。

注意： 仅对有关联订单需求的券进行该操作

参数:

associateInfo - the associate info

返回:

the associate time

抛出:

PayException - the pay exception

disassociate

@POST(value="v3/marketing/busifavor/coupons/disassociate")
AssociateTime disassociate(@Body
                                                                                       FavorAssociateInfo associateInfo)
                                                                                throws PayException

商家券取消关联订单信息API

取消商家券与订单信息的关联关系。

注意： 建议取消前调用查询接口，查到当前关联的商户单号并确认后，再进行取消操作

参数:

associateInfo - the associate info

返回:

the associate time

抛出:

PayException - the pay exception

budget

@PATCH(value="v3/marketing/busifavor/stocks/{stock_id}/budget")
FavorBudgetResponse budget(@Path(value="stock_id")
                                                                                            String stockId,
                                                                                            @Body
                                                                                            FavorBudgetParams params)
                                                                                     throws PayException

修改批次预算API

商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量

参数:

stockId - the stock id

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

updateStock

@PATCH(value="v3/marketing/busifavor/stocks/{stock_id}")
cn.felord.retrofit.VoidResponse updateStock(@Path(value="stock_id")
                                                                                                      String stockId,
                                                                                                      @Body
                                                                                                      FavorUpdateParams params)
                                                                                               throws PayException

修改商家券基本信息API

商户可以通过该接口修改商家券基本信息，已创建商家券批次，且修改时间位于有效期结束时间前

参数:

stockId - the stock id

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

refund

@POST(value="v3/marketing/busifavor/coupons/return")
GenericPayResponse<OffsetDateTime> refund(@Body
                                                                                                FavorRefundParams params)
                                                                                         throws PayException

申请退券API

商户可以通过该接口为已核销的券申请退券

参数:

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

deactivate

@POST(value="v3/marketing/busifavor/coupons/deactivate")
GenericPayResponse<OffsetDateTime> deactivate(@Body
                                                                                                        FavorDeactivateParams params)
                                                                                                 throws PayException

使券失效API

前置条件：券的状态为CouponState.SENDED

商户可以通过该接口将可用券进行失效处理，券被失效后无法再被核销

参数:

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

returnReceipts

@POST(value="v3/marketing/busifavor/subsidy/return-receipts")
FavorReturnSubsidyResponse returnReceipts(@Body
                                                                                                         FavorSubsidyReturnParams params)
                                                                                                  throws PayException

营销补差回退API

商户通过该接口可回退补差款

参数:

params - the params

返回:

wechat response entity

抛出:

PayException - the pay exception

payMakeup

@POST(value="v3/marketing/busifavor/subsidy/pay-receipts")
FavorSubsidyListResponse payMakeup(@Body
                                                                                               FavorSubsidyParams params)
                                                                                        throws PayException

营销补差付款API

该API主要用于商户营销补贴场景， 支持基于单张券进行不同商户账户间的资金补差， 从而提升财务结算、资金利用效率。具体可参考操作文档

参数:

params - the params

返回:

the wechat response entity

抛出:

PayException - the pay exception

从以下版本开始:

1.0.13.RELEASE

queryMakeup

@GET(value="v3/marketing/busifavor/subsidy/pay-receipts/{subsidy_receipt_id}")
FavorSubsidyResponse queryMakeup(@Path(value="subsidy_receipt_id")
                                                                                                                 String subsidyReceiptId)
                                                                                                          throws PayException

查询营销补差付款单详情API

查询商家券营销补差付款单详情

参数:

subsidyReceiptId - the subsidyReceiptId

返回:

the wechat response entity

抛出:

PayException - the pay exception

从以下版本开始:

1.0.13.RELEASE