Kernlift

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.1 address cannot receive webhooks.
  • An admin account with config.read and config.write.
  • At least one active plan on /admin/plans. See Manage pricing plans.

Create test resources with the payment provider

ProviderChoose it for
StripeSubscription checkout, portal and refunds
CreemHosted checkout; see adapter compatibility
PayPalOne-time orders with a sandbox buyer
DodoPaymentsHosted checkout linked to a product ID
WeChat PayCNY one-time payment with a QR code
AlipayCNY one-time payment on Alipay's computer-website cashier, with refunds
WaffoMerchant 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.com and https://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 to https://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/billing shows 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 a billing.fulfilment.failed entry 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.

Reference

Next steps