payment-spring-boot: a Spring Boot starter for WeChat Pay V3

What the starter covers, and for whom

payment-spring-boot is a Spring Boot starter for WeChat Pay V3 payments in Java. The README describes it as the most complete and useful WeChat Pay V3 Spring Boot component, supporting WeChat coupons, vouchers, merchant coupons, smart business districts, merchant transfers to balance, official account payment, mini program payment, profit sharing, payment scoring, combined payment, pay-first cards and the e-commerce settlement product, covering all the WeChat Pay function APIs while meeting the development needs of multiple service providers and multiple merchants.

That last clause is the one worth dwelling on. The multi-tenant idea runs through the configuration and the API surface, where a tenant id identifies which merchant configuration an operation uses, and the example code selects the merchant with a constant TENANT_ID before calling into the provider. For a service provider integrating on behalf of many merchants, that is the difference between a usable library and one that assumes a single set of credentials.

The distribution is a starter rather than a library, which matters for what you can expect. The Maven coordinates are cn.felord:payment-spring-boot-starter, and the project is hosted under the dromara organisation with the README also pointing at a Gitee mirror. The repository itself is a multi-module Maven build with payment-spring-boot-starter/ and payment-spring-boot-autoconfigure/ directories, plus docs/ and apidocs/ directories.

The module split is the usual Spring Boot arrangement. The starter carries the dependency wiring for consumers, and the autoconfigure module holds the conditional configuration that decides which beans exist for a given tenant and profile.

The stated goal is one-click integration, shielding the complexity behind an API-friendly surface, so that a developer can get to a working payment call quickly. The README also links a WeChat consultation entry point and two QQ groups for support, which is a sign of a project with a Chinese user base rather than a purely international one.

The WeChat Pay public key migration, and the flag that controls it

The most consequential piece of the documentation is a migration, and it is easy to read past.

WeChat officially introduced the WeChat Pay public key product to replace the original WeChat platform certificate, and this project has been adapted to it. The configuration lives under a wechat pay v3 block keyed by tenant id, and the relevant keys are enable-wechat-pay-public, which defaults to false, wechat-pay-public-key-id, wechat-pay-public-key-path pointing at a pem file, an absolute path variant, and switch-verify-sign-method, also defaulting to false.

The rules for who needs what are spelled out. For older merchants who do not use the public key, none of these parameters are needed and verification defaults to the WeChat platform certificate. For newly onboarded merchants, WeChat enables the payment public key by default, so the parameters are required, except switch-verify-sign-method which does not need to be configured in that case. And an older merchant that does use the public key needs the parameters set and switch-verify-sign-method turned on.

Then there is a warning in bold text about what to do after the migration: once you have finished switching from the platform certificate to the WeChat Pay public key, you must set switch-verify-sign-method to false or delete the field.

That last instruction is the kind of detail that causes outages. The flag is a toggle between two verification methods, and leaving it on after the switch means the application continues verifying with the mechanism you have just moved away from. Any migration checklist should include it.

The reference for the public key itself is WeChat's own documentation on the merchant side, linked from the README.

Turning the starter on, and the shape of a payment call

Enabling the module is an explicit annotation, not an automatic starter effect. The README says you need to enable payment manually with the @EnableMobilePay annotation, and shows the configuration class that carries it:

import cn.felord.payment.autoconfigure.EnableMobilePay;
import org.springframework.context.annotation.Configuration;

@EnableMobilePay
@Configuration
public class PayConfig {
}

The API layer is organised around a provider object that is selected per tenant. The example is a Spring MVC controller that injects WechatApiProvider, and the call chain is directPayApi for the tenant followed by the specific operation:

        return wechatApiProvider.directPayApi(TENANT_ID)
                .jsPay(payParams)
                .getBody();

The README advises wrapping WechatApiProvider in your own service layer in practice, which is sensible advice for anything that becomes a payment flow: the controller in the example is a demonstration, not a design to copy.

The parameters object carries the payment details. The out trade no is the merchant-side unique order number, which the README suggests be the merchant's own payment order number, a primary key or a unique identifier. The notify url points at the callback endpoint, here /wxpay/callbacks/transaction. The amount object carries the total in the smallest currency unit, and the payer object carries the openid, which for this payment type is required and must be bound to the same appid.

The controller example also documents the recommended order of operations, which is the part that matters operationally: generate the product order, generate the corresponding payment order, perform the payment operation, update on the payment result callback, and finish. The callback status update logic is handled at /wxpay/callbacks/transaction and needs idempotent handling.

The controller is annotated with @Profile for wechat and dev, which is how the example keeps itself out of other environments.

Reporting and reconciliation endpoints

Beyond taking payments, the example shows the reconciliation side, which is where payment integrations usually get their complexity.

There is a trade bill download endpoint that builds a TradeBillParams with a bill date and a bill type of ALL, then hands it to the direct pay API and returns the result as a ResponseEntity of a Resource. And there is a fund flow bill endpoint for the fund settlement statement, with the same shape.

The README notes in both cases that if you want to parse the content you implement that yourself, which is a reasonable division. The library's job is to sign the request and hand back the bytes; interpreting a WeChat statement format is application logic that changes and that you probably want under your own tests.

That endpoint set, trade bill and fund flow bill, is what you need for the monthly reconciliation that any real merchant operation involves. A payment integration that only takes payments and never reconciles is a payment integration that eventually finds money it cannot explain.

The rest of the API surface is described in the README as covering most of the direct merchant and service provider interfaces, with an API registry class, WechatPayV3Type, that you can use to look up the interface you need. The linked API listing and changelog pages are both marked as temporarily unavailable in the README, which is worth knowing before you plan a morning around them, since the registry class is the documented fallback for discovery.

Limits: a single payment provider, a moving API and a thin documentation trail

The limits are the ones you would expect from a focused integration library.

The first is that it is WeChat only. Nothing here helps with Alipay, Stripe or any other provider, and the package is named for what it does. That is fine if WeChat is your market, which for the project's audience it evidently is, and it is a hard dependency if you serve several markets.

The second is that it tracks a moving API. WeChat Pay V3 has changed its verification model at least once in the period this project covers, with the public key replacing the platform certificate, and the README's own warning about setting switch-verify-sign-method to false afterwards is evidence of how these changes land. A WeChat-only library is easier to keep current than a general payment abstraction, but it still means you upgrade when WeChat changes something, and the migration instructions are in a README rather than in a changelog with version notes.

The third is the documentation state, which the README is candid about. The GitHub Pages documentation for the project, the API listing, the changelog and the quick start section are all struck through and marked as temporarily unavailable, and the README says to consult the WeChat payment public key documentation for that part instead. There is a docs/ directory in the repository and an apidocs/ directory, so material exists, but the published entry point that a new user is sent to is broken.

The fourth is the version scheme, which is a little odd. The Maven coordinates in the README give the version as 1.0.21.RELEASE, while the tagged releases are numbered 1.0.21, 1.0.20 and 1.0.19.RELEASE. The artifact id is payment-spring-boot-starter, and the version string in the coordinates does not obviously match the tag, so you should check what is actually in Maven Central rather than assuming.

The fifth is the JDK note. The README recommends Open JDK, and links an issue about it that points at an FBI warning.

This starter against the official WeChat Pay SDK and against writing the calls by hand

Two comparisons make the choice clearer.

The first is against the official WeChat Pay Java SDK. The starter's pitch, compared with working directly against any SDK, is what the layer adds: Spring Boot autoconfiguration, multi-tenant merchant configuration, and the request signing and verification wiring already connected.

The cost is the layer. When something does not work, you are debugging through a starter rather than against the SDK, and the WeChat Pay API surface changes more often than the Spring Boot conventions do, so the starter has to absorb changes that the official SDK absorbs more directly.

The second comparison is against writing the calls by hand, which is what many integrations start with. The README's own framing is that it shields the complexity and gives an API-friendly surface, and the multi-tenant selection is the part that is genuinely hard to redo. If you have one merchant and one endpoint, the official SDK with a Spring service wrapper is a morning's work. If you have twenty merchants behind one service provider account and you need profit sharing, payment scoring and the settlement product, then the tenant-aware configuration and the shared request plumbing are worth taking rather than rebuilding.

The practical deciding factor is the multi-tenant requirement. A single-merchant integration does not need this starter. A service provider integration probably does.

Editorial conclusion

Adopt payment-spring-boot if you are integrating WeChat Pay V3 into a Spring Boot service and want the request signing, certificate handling and multi-tenant merchant configuration already worked out, particularly if you run service providers with several merchants. Do not adopt it if you need WeChat Pay V2 or a non-Spring stack. Verify first which WeChat Pay verification method your merchant uses, since the switch from platform certificates to the public key is a per-merchant choice with a flag you must set correctly, and check that the API you need is implemented in the version you pin.

Frequently asked questions

Official sources

1. dromara/payment-spring-boot on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases