Kernlift

Payment lifecycle

How a checkout becomes a paid order: server-side pricing, provider confirmation by webhook or callback, idempotent settlement and refunds.

A payment in Kernlift moves through four stages: the server creates an order at the plan's price, the buyer pays on the provider's hosted checkout, the provider confirms the payment, and settlement turns the order into an invoice and notifies the fulfilment plugins, which deliver what the plan sells. To connect a provider, see Connect a payment provider.

The lifecycle at a glance

StageTriggered byResult
CheckoutPOST /api/billing/checkout from a signed-in buyerA pending order and a hosted checkout URL
PaymentThe buyer, on the provider's pageNothing changes locally yet
ConfirmationA signed webhook, or the return callback querying the providerThe order becomes paid, failed or canceled
SettlementA paid confirmationInvoice and subscription, committed first
FulfilmentSettlement, after the order is committedEvery enabled billing.fulfilment plugin is notified once; the built-in one grants the plan's credits
RefundAn administratorA refund record; fulfilment plugins are notified when it succeeds

One provider is active at a time and charges every plan, with one exception: a plan priced in CNY goes to a mainland wallet when one is enabled and fully configured, WeChat Pay first and Alipay when WeChat Pay is not ready, and every other currency stays with the active provider. A request may also name a provider explicitly. The providers share this lifecycle. They differ in what they support after checkout.

ProviderSubscriptionsCustomer portalRefunds from the admin console
StripeYes, renewing monthly or yearly by the plan's intervalYesYes
CreemCancel and resumeYesNo, in the Creem dashboard only
PayPalNo, one-time payments onlyNoNo
DodoPaymentsNo lifecycle actionsNoNo
WeChat PayNo, CNY one-time payments onlyNoYes
AlipayNo, CNY one-time payments onlyNoYes
WaffoYes, through one monthly and one yearly subscription product created in WaffoNoNo, in the Waffo dashboard only

Stripe and Waffo can also show a promotion code field at checkout when Allow promotion codes at checkout is on. The invoice then records what the buyer actually paid. See Offer promotion codes.

Checkout is priced on the server

The request names a plan key. The server loads that plan and compares the amount, currency and checkout mode the client sent against it. The server rejects any difference before it calls a provider.

Rejection (HTTP 409)Cause
unknown_planNo plan has that key
plan_inactiveThe plan is not active
amount_mismatchAmount, currency or checkout mode differs from the plan
product_mismatchThe request names a different product than the plan sells
plan_interval_mismatchThe plan bills as a subscription but does not renew monthly or yearly, or the reverse
provider_unsupportedWeChat Pay or Alipay would charge the plan, but it is a subscription or not priced in CNY
A fulfiller's own codeAn enabled fulfilment plugin refused the purchase in canCheckout

When the checks pass, a pending order is stored with the plan's price. If the active provider is not configured, the order is marked failed, a not-configured event is recorded and the request returns 409. Otherwise the provider creates a hosted checkout, and its success and cancel URLs point back at /api/billing/callback/:provider.

WeChat Pay has no hosted checkout. Its Native order returns a weixin:// code URL, which is stored on the order, and the buyer is sent to /app/billing/pay/<orderId> on your own site. That page draws the QR code for the signed-in owner of a pending order, polls the server for the order's state every three seconds, and moves on to the success URL once it is paid. The code expires after two hours.

Alipay sends the buyer straight to its computer-website cashier with an RSA2-signed address that expires after two hours. Waffo creates a hosted checkout session priced from the plan (tax included) on the Waffo product that matches it: the one-time product, or the monthly or yearly subscription product.

Only the provider can mark an order paid

The return URL a buyer lands on is not proof of payment, because anyone can open it. Payment state changes only through one of two server-side confirmations.

The signed webhook. /api/billing/webhook/:provider verifies the provider's signature on the raw request body before reading anything. It finds the local order id in the event, then maps the event type to paid, failed or canceled. Each event id is stored, so a repeated delivery returns the stored result and has no further effect. An event with an invalid signature is stored as failed and changes nothing. Registering the webhook for each provider is covered in Connect a payment provider.

The return callback. /api/billing/callback/:provider ignores the status query parameter except for logging. It queries the provider for the stored checkout and settles only when the provider reports it paid. Otherwise the order is left for the webhook. The buyer is then redirected to the success or cancel URL.

Whichever arrives first settles the order, and the other makes no further change. A failed webhook can be retried from the admin console, which re-applies a validly signed payload under a new event id.

WeChat Pay follows the same rule with two differences. Its notification is verified with the WeChat Pay public key and then decrypted with the APIv3 key, and both the notification and the server-side order query settle only when the amount in fen equals the order amount and the currency is CNY.

Alipay's notification carries its signature in the form body and is verified with the Alipay public key; it settles only when the app id, the seller id (when saved) and the amount match the order. Its server-side alipay.trade.query settles only when the signature over the raw response verifies and the amount matches. Waffo's webhook is verified with the saved webhook public key, and its server-side check looks up the payments recorded for the order. Both record the amount actually charged, so a promotion code shows on the invoice.

Settlement is idempotent

Settlement runs from both the webhook and the callback, so every step is safe to repeat:

  1. The order status becomes paid.
  2. An invoice invoice_<orderId> is written.
  3. For a subscription, subscription_<orderId> is written with the provider subscription id. If the callback settled first, a later webhook fills the id in.
  4. Once those writes are committed, every enabled fulfilment plugin is notified of the paid order.

Fulfilment comes after the commit

Billing owns orders, payments and refunds. What a paid order entitles the buyer to is defined by the plugin that sells it, which contributes a fulfiller to the billing.fulfilment server slot. Billing code does not reference any fulfiller by name.

HookCalledPurpose
canCheckoutBefore an order or a payment session is createdRefuse a purchase with a code and a reason
onOrderPaidAfter the order is committed as paid, once per orderDeliver what the plan sells
onOrderRefundedAfter a refund succeeds at the provider, once per refundTake back what the refund covers

Each call is recorded in billing_fulfilments, one row per order, fulfiller and event. Inserting the row is the claim, so a webhook and a callback that settle the same order at the same moment still run each fulfiller once. A fulfiller that throws does not undo the payment. The row is marked failed, an audit entry is written, and the scheduled jobs retry it after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After the sixth attempt the row is abandoned and left for the operator. A paid event whose order has since been refunded or canceled is abandoned and not delivered. Fulfillers of switched-off plugins are not called.

The template ships one fulfiller, plan-credits, contributed by the foundation plugin. It grants the plan's included credits once, as a purchase with source billing.order.<orderId>. See Credits ledger and Write a fulfilment plugin.

Refunds and subscription changes

Refunds are created from the admin console and recorded as pending, succeeded, failed or not_configured. Stripe refunds against a PaymentIntent or Charge, resolving a Checkout Session to its PaymentIntent first. WeChat Pay refunds through its refund API. A synchronous SUCCESS succeeds at once, and PROCESSING stays pending until the signed REFUND.SUCCESS notification arrives. Alipay refunds through alipay.trade.refund with the local refund id as out_request_no, so a repeated request refunds once. The other adapters report refunds as unsupported; for Waffo, refunds and subscription changes are made in the Waffo dashboard. Whether a refund is full is judged against the amount the buyer paid. When a refund succeeds, fulfilment plugins receive onOrderRefunded with the amount and whether it covers the whole order. Each plugin determines what a refund takes back.

Cancelling a subscription sets it to end at the period end, and resuming clears that flag. Both need the provider subscription id that settlement stored.

What is recorded

Every checkout, webhook, callback and not-configured attempt is stored with its signature result, status and raw payload, and administrators can inspect each one. Orders, invoices, subscriptions, refunds and fulfilments are separate records.

Files

src/server/db/repositories/billing-payment.repository.ts
src/server/functions/billing-payment.ts
src/server/payments/wechatpay.ts
src/server/payments/alipay.ts
src/server/payments/waffo.ts
src/server/billing/fulfilment.ts
src/server/billing/fulfilment-types.ts
src/server/billing/plan-credits-fulfiller.ts
src/server/db/repositories/billing-fulfilment.repository.ts
src/components/billing/app-billing-pages.tsx
src/components/billing/billing-workspace.tsx
src/components/billing/wechat-pay-checkout.tsx

Next steps