Why is Stripe payment failing for my members?

A failed payment is the worst thing that can happen to a paid membership — it means a subscriber who's trying to give you money can't. And if it's happening silently (the payment form shows an error but you have no idea as the blog owner), you could be losing revenue without knowing it. Here's how to find and fix the problem.

Step 1 — Verify your BYOK Stripe key

VeloCMS uses Bring Your Own Keys (BYOK) for Stripe — you connect your own Stripe account. Go to Admin → Settings → Membership and open the Reader Subscriptions section. There is no separate connection-status indicator: VeloCMS checks your Stripe Secret Key against the Stripe API when you save, and shows an error if Stripe rejects it. If saving fails, or payments fail with an authentication error, the secret key you entered may be wrong, expired, or from the wrong Stripe account.

• In your Stripe dashboard, go to Developers → API keys.
• For production, use the live secret key (starts with sk_live_). For testing, use the test secret key (starts with sk_test_).
• Never use the publishable key (starts with pk_) as the secret key — it won't work for server-side operations.
• If you created a restricted key, make sure it has read+write permissions for: Checkout Sessions, Customer Portal, Customers, Payment Intents, Prices, Products, Subscriptions, and Webhook Endpoints.
• In VeloCMS Admin → Settings → Membership → Reader Subscriptions, paste the correct key into Stripe Secret Key and click Save. VeloCMS immediately verifies the key with a test API call and shows an error if it is rejected.

Step 2 — Check webhook endpoint registration

Stripe uses webhooks to tell VeloCMS when a payment succeeds, fails, or when a subscription status changes. Without a working webhook, VeloCMS can't activate member access after a successful payment — the member pays but their account stays locked.

• In your Stripe dashboard, go to Developers → Webhooks.
• Look for an endpoint with the URL format: https://yourslug.velocms.org/api/member-webhook/yourslug.
• If no such endpoint exists, add one yourself: in Stripe go to Developers → Webhooks → Add endpoint and paste the address shown next to Webhook URL under Reader Subscriptions in VeloCMS Admin → Settings → Membership. VeloCMS does not register the endpoint for you.
• If the endpoint exists but shows recent failures in Stripe, click on it and look at the failed event details. Common errors: 401 (wrong webhook secret), 500 (server error — check Railway logs), 404 (VeloCMS service is down).
• Copy the Webhook Signing Secret from Stripe and paste it into the Webhook Secret field under Reader Subscriptions in VeloCMS Admin → Settings → Membership. Without this, VeloCMS rejects all incoming webhook events.

Test mode vs live mode mismatch

Stripe has two completely separate environments: test mode and live mode. API keys, customers, products, prices, and webhooks from test mode don't exist in live mode and vice versa. A common mistake is setting up products and prices in test mode, then switching to a live secret key — VeloCMS tries to look up the product in live mode and can't find it.

Customer portal configuration

If payment itself works but members can't manage their subscriptions (cancel, update card, view invoices), the Stripe Customer Portal may not be configured. In your Stripe dashboard, go to Settings → Billing → Customer portal. Enable the portal and at minimum enable: invoice history, subscription cancellation, and payment method updates. Without these settings, the portal link in VeloCMS Admin → Billing returns a generic Stripe error page.