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
| Stage | Triggered by | Result |
|---|---|---|
| Checkout | POST /api/billing/checkout from a signed-in buyer | A pending order and a hosted checkout URL |
| Payment | The buyer, on the provider's page | Nothing changes locally yet |
| Confirmation | A signed webhook, or the return callback querying the provider | The order becomes paid, failed or canceled |
| Settlement | A paid confirmation | Invoice and subscription, committed first |
| Fulfilment | Settlement, after the order is committed | Every enabled billing.fulfilment plugin is notified once; the built-in one grants the plan's credits |
| Refund | An administrator | A 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.
| Provider | Subscriptions | Customer portal | Refunds from the admin console |
|---|---|---|---|
| Stripe | Yes, renewing monthly or yearly by the plan's interval | Yes | Yes |
| Creem | Cancel and resume | Yes | No, in the Creem dashboard only |
| PayPal | No, one-time payments only | No | No |
| DodoPayments | No lifecycle actions | No | No |
| WeChat Pay | No, CNY one-time payments only | No | Yes |
| Alipay | No, CNY one-time payments only | No | Yes |
| Waffo | Yes, through one monthly and one yearly subscription product created in Waffo | No | No, 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_plan | No plan has that key |
plan_inactive | The plan is not active |
amount_mismatch | Amount, currency or checkout mode differs from the plan |
product_mismatch | The request names a different product than the plan sells |
plan_interval_mismatch | The plan bills as a subscription but does not renew monthly or yearly, or the reverse |
provider_unsupported | WeChat Pay or Alipay would charge the plan, but it is a subscription or not priced in CNY |
| A fulfiller's own code | An 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:
- The order status becomes
paid. - An invoice
invoice_<orderId>is written. - For a subscription,
subscription_<orderId>is written with the provider subscription id. If the callback settled first, a later webhook fills the id in. - 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.
| Hook | Called | Purpose |
|---|---|---|
canCheckout | Before an order or a payment session is created | Refuse a purchase with a code and a reason |
onOrderPaid | After the order is committed as paid, once per order | Deliver what the plan sells |
onOrderRefunded | After a refund succeeds at the provider, once per refund | Take 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.