Mastering WeChat Pay V3: Build Coupon APIs with Spring Boot Starter

1. Introduction

After a 12‑day gap since the last original share, the author apologizes for delayed content and now presents useful information about developing WeChat Pay voucher features.

2. WeChat Pay Marketing

WeChat Pay offers merchant coupons, vouchers, and instant discounts to attract and retain users. From a development perspective these features are more complex than basic payment integration and involve additional strategies.

3. Preparation Before Development

WeChat Merchant Account

Visit https://pay.weixin.qq.com to enable WeChat Pay. A merchant number is required, and the public account appid and the appid of mobile or mini‑program must be bound to the merchant account.

WeChat Open Platform Account

Visit https://open.weixin.qq.com for third‑party platform, mobile app, public platform, or website development. The appid of the public service account or mobile app must be bound to the open platform.

WeChat Public Platform Service Account

Apply at https://mp.weixin.qq.com . Make sure it is a service account, not a subscription or personal account , because only service accounts are used for enterprise development. After certification, bind it with the merchant and open platform accounts.

4. WeChat Pay V3 Workflow

Collect API parameters.

Sign the parameters.

Send the API request.

Validate the response source to ensure it comes from the payment server.

Parse the response.

Respond to callback requests.

Based on this workflow, the author designed a small model using coupon batch creation as an example.

/**
 * Create coupon batch API.
 *
 * @param params the params
 * @return the wechat response entity
 */
public WechatResponseEntity<ObjectNode> createStock(StocksCreateParams params) {
    WechatResponseEntity<ObjectNode> wechatResponseEntity = new WechatResponseEntity<>();
    // 1. Organize parameters according to request type
    this.client().withType(WechatPayV3Type.MARKETING_FAVOR_STOCKS_COUPON_STOCKS, params)
        // 2. Process parameters
        .function(this::createStocksFunction)
        // 3. Consume the result
        .consumer(wechatResponseEntity::convert)
        .request();
    return wechatResponseEntity;
}

Any WeChat Pay V3 API can be wrapped using the same model.

5. WeChat Pay Development Kit

The author packaged the design as a Spring Boot Starter with virtually no third‑party dependencies, using only Spring's RestTemplate and Jackson libraries. The coupon module is already completed and tested.

Integration

<dependency>
    <groupId>cn.felord</groupId>
    <artifactId>payment-spring-boot-starter</artifactId>
    <version>1.0.0.RELEASE</version>
</dependency>

Configuration

Add the following to application.yaml in a Spring Boot project:

wechat:
  pay:
    v3:
      # Application appId (required)
      app-id: xxxxxxxx
      # API secret (required)
      app-secret: xxxxxxxxx
      # API v3 secret (required)
      app-v3-secret: xxxxxxxx
      # Merchant ID (required)
      mch-id: xxxxxxx
      # Partner key (optional)
      partner-key:
      # Merchant domain for callbacks (required)
      domain: https://xxxx.xxx.com
      # Merchant API certificate (required)
      cert-path: apiclient_cert.p12
      mp:
        app-id: xxxxxxxxx
        app-secret: xxxxxxxxxxxxxxxxxxx

Enable the starter with the annotation @EnableWechatPay in a configuration class.

@EnableMobilePay
@Configuration
public class PayConfig {
}

Note: The API wechat.pay.v3.app-id must have a valid value before the related APIs become usable.

API Usage

Inject the APIs:

// Payment API
@Autowired
WechatPayApi wechatPayV3Api;
// Marketing API
@Autowired
WechatMarketingApi wchatMarketingApi;

Example: query coupons under the merchant:

@Test
public void v3MchStocks() {
    StocksQueryParams params = new StocksQueryParams();
    params.setOffset(0);
    params.setLimit(10);
    WechatResponseEntity<ObjectNode> response = wechatPayV3Api.queryStocksByMch(params);
    System.out.println("objectNodeWechatResponseEntity = " + response);
}

If you have any questions about WeChat Pay, feel free to leave a comment; the author promises to answer.