Connect a payment provider
Buyers pay on Stripe, Creem, PayPal, DodoPayments, WeChat Pay, Alipay or Waffo, and a confirmed payment marks their order paid.
Payments run through one active provider at a time. WeChat Pay and Alipay are the exception. Once enabled and complete, they charge every plan priced in CNY, WeChat Pay first and Alipay when WeChat Pay is not ready, and the active provider charges plans in other currencies. You connect providers in the admin console, register the webhook, and take a test payment. Payments need no environment variables.
Before you begin
- A provider account and API credentials. Start in test mode, except for WeChat Pay, which requires a live merchant account.
- The public URL of your deployment. A local
127.0.0.1address cannot receive webhooks. - An admin account with
config.readandconfig.write. - At least one active plan on
/admin/plans. See Manage pricing plans.
Create test resources with the payment provider
| Provider | Choose it for |
|---|---|
| Stripe | Subscription checkout, portal and refunds |
| Creem | Hosted checkout; see adapter compatibility |
| PayPal | One-time orders with a sandbox buyer |
| DodoPayments | Hosted checkout linked to a product ID |
| WeChat Pay | CNY one-time payment with a QR code |
| Alipay | CNY one-time payment on Alipay's computer-website cashier, with refunds |
| Waffo | Merchant of record: hosted checkout for one-time and subscription plans, sales tax handled by Waffo |
Enter the provider settings
Open Payment Config
Go to Settings → Payment Config (/admin/config/payment). Each provider card shows Missing credentials or Ready, and Webhook missing or Webhook ready. Select the provider you want to set up.
Set the checkout routes
Under Checkout routes:
- Success URL: where the buyer lands after a confirmed payment, for example
https://<your-domain>/app/billing. - Cancel URL: where the buyer lands otherwise, for example
https://<your-domain>/pricing. - API base URL: the provider API to call. Creem, PayPal and DodoPayments default to
https://api.creem.io,https://api-m.sandbox.paypal.comandhttps://test.dodopayments.com. Change it when you move between test and live. Stripe ignores this field, because the key determines test or live. WeChat Pay defaults tohttps://api.mch.weixin.qq.com, its only environment. Alipay defaults to the sandbox gateway; Waffo has one address,https://api.waffo.ai, and its key decides test or live. - Allow promotion codes at checkout: see Offer promotion codes.
The buyer returns through your own domain before reaching the success URL, so use your public domain here.
Paste the API credentials
Under Credentials, fill in the fields for the selected provider:
Use the field mapping in your provider’s guide above.
Secret fields are never shown again after saving. Leave one blank to keep the stored value.
Register the webhook
Follow your provider guide to register its HTTPS endpoint, select the supported events and save its verification credentials. WeChat Pay and Alipay include the notification URL with each order.
Activate the provider
Tick Set as active provider and click Save provider. The card shows Active and Webhook ready, and the Runtime panel shows the active provider. Unticking and saving the active provider leaves no provider active. Saving another provider unticked does not change the active one. Ticking WeChat Pay or Alipay turns it on for CNY plans and makes it the active provider only when none is active. The Capabilities panel shows whether the portal, subscriptions, refunds and promotion codes are available.
Offer promotion codes
Turn on Allow promotion codes at checkout in Checkout routes and click Save provider. The switch is stored once (payment.checkout.allow_promotion_codes) and is off by default. Stripe and Waffo then show a code field on their hosted checkout; the other providers ignore the switch, and their Capabilities panel shows promotion codes as unsupported. Create the codes in the provider's own dashboard.
The invoice records the amount actually paid, taken from the signed webhook or the server-side confirmation, while the amount due stays at the plan price. A refund of everything the buyer paid counts as a full refund.
Verify
Sign in as a normal user, open /pricing and buy a plan with the provider's test card or sandbox buyer. Then check:
- Security → Webhooks (
/admin/billing-webhooks) lists the provider's event with a valid signature. - Commerce → Orders (
/admin/orders) shows the order as paid. - The buyer's
/app/billingshows the invoice, and the plan's credits appear on/app/credits. The built-in fulfilment plugin grants credits after the order is committed. If they are missing, look for abilling.fulfilment.failedentry on/admin/audit. - For WeChat Pay, the buyer is sent to
/app/billing/pay/<order>, scans the QR code with WeChat, and the page moves on to the success URL within a few seconds of paying. - For Alipay, the buyer is sent to Alipay's cashier and comes back through
/api/billing/callback/alipay, which queries the trade before the order is marked paid.
pnpm validate:billing checks the order state machine, not-configured paths and signature handling. pnpm validate:wechat-pay checks WeChat Pay signing, decryption, amount checks and routing by currency without calling WeChat Pay. pnpm validate:alipay, pnpm validate:waffo and pnpm validate:promotion-codes do the same for Alipay, Waffo and discounted totals. To test against the real sandbox, run pnpm validate:external with the provider credentials saved.
Troubleshooting
The buyer is sent to /system/payment-failed from the pricing page
Checkout was rejected. Open Webhooks for the checkout.not_configured or checkout.failed event and its error, then complete the credentials on Payment Config. DodoPayments also needs a product id.
Webhooks fail the signature check
Confirm the saved Webhook secret is the signing secret of this endpoint, and for DodoPayments the full whsec_… value. Stripe and DodoPayments reject events more than 300 seconds away from the server clock, so check the server time. A proxy that rewrites the request body also breaks the signature.
The buyer lands on a missing page after paying
A database seeded before the default changed can still hold http://127.0.0.1:5173/app/billing/orders, which has no route. Set Success URL to a page that exists, such as https://<your-domain>/app/billing.
WeChat Pay or Alipay checkout is refused with provider_unsupported
WeChat Pay and Alipay charge CNY one-time payments only. On /admin/plans, price the plan in CNY with the one-time or lifetime interval, or use another provider for that plan.
The order stays pending
The webhook has not arrived and the buyer did not return to your site. Check that the endpoint is registered for the right events, then resend the event from the provider dashboard.