Stripe Integration

Stripe shows up in two separate places on VeloCMS, and it helps to keep them apart. The first is your own VeloCMS subscription: you pay VeloCMS for your plan, and Stripe handles that billing. The second is your readers paying you for memberships, which runs through your own Stripe account. The two never share keys or webhooks.

Managing your VeloCMS subscription

Admin → Billing shows your plan, trial status and renewal date. The Manage subscription button opens the Stripe customer portal, where you update your card, download invoices, change plans or cancel. VeloCMS doesn't store your card details; the portal is hosted by Stripe. If the portal can't open, the page says why, usually that no Stripe customer is linked to the site yet, in which case contact support.

Charging readers with your own Stripe account

Reader memberships are bring-your-own-Stripe. Your readers pay you directly, VeloCMS never holds the money, and VeloCMS takes no cut of what you earn. Stripe's own processing fees still apply, because that's your account with them. Everything is configured at Admin → Settings → Membership.

1. In your Stripe Dashboard, create an API key. A restricted key is the safer option. If you use one, give it access to Customers, Subscriptions, PaymentIntents, Prices and Products. A full secret key (starting sk_) also works.
2. In Admin → Settings → Membership, switch on Accept reader subscriptions, then paste the key into Stripe Secret Key and your publishable key into Stripe Publishable Key.
3. Set the Tier Name, Monthly Price, Yearly Price, Currency and the list of Benefits your paid readers get.
4. Create the webhook endpoint described below, then paste its signing secret into the Webhook Secret field and save.

When you save, VeloCMS checks the secret key against Stripe, so a mistyped or under-permissioned key is caught right away instead of failing later at checkout. Keys must start with sk_live_, sk_test_, rk_live_ or rk_test_. The secret key and webhook secret are stored encrypted and can't be read back after you save, which is why a saved key shows a masked "key saved" placeholder instead of the value. Your publishable key is designed to be public, so it's stored as plain text.

Set up the webhook

Stripe tells VeloCMS when a reader subscribes, renews or cancels by calling a webhook. In your Stripe Dashboard go to Developers → Webhooks and add an endpoint. The exact URL for your site is shown under the Webhook Secret field in Admin → Settings → Membership. It has this shape, with your own site name in both places:

https://yourblog.velocms.org/api/member-webhook/yourblog

Enable these four events on the endpoint: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted and invoice.payment_failed. Then copy the signing secret Stripe generates (it starts with whsec_) into the Webhook Secret field.

Duplicate and failed deliveries

Stripe retries deliveries it thinks failed, for up to three days. VeloCMS records each event it handles, so an event Stripe sends twice is acknowledged without being applied twice. If processing itself fails, VeloCMS lets the retry go through again rather than swallowing the event. Every request is also checked against your signing secret, and anything that doesn't match is rejected.

Refunds on your VeloCMS subscription

If a refund is issued on your VeloCMS subscription, your site doesn't switch off instantly. It enters a 14-day read-only window, during which changes to the site are blocked. After that window the account is suspended like any other lapsed subscription. Re-subscribing in the window restores normal access. The refund terms themselves are on the Refund Policy page.

When something doesn't work