Connecting Stripe for Subscriptions

Built-in membership uses Stripe to process subscriber payments. Before you can accept paid subscriptions, you need to connect your Stripe account.

This page covers the Settings → Membership → Payments panel — the Stripe connection for built-in membership. If you use Listener Support link-mode donations, that connection lives separately in Settings → Listener Support → Stripe. Both panels store the same underlying Stripe keys; saving through one is reflected in the other.

Where to Find It

Benecaster → Settings → Membership → Payments

The panel shows two key sets side by side — Test keys and Live keys — with a single “Use Stripe test mode” toggle above them.

Step 1: Get Your Stripe API Keys

In your Stripe Dashboard, go to Developers → API keys.

You need two keys for each mode:

Publishable key — starts with pk_test_ (test) or pk_live_ (live)
Secret key — starts with sk_test_ (test) or sk_live_ (live)

Stripe also provides Restricted keys — these will not work. Benecaster requires standard secret keys.

Step 2: Enter Your Keys

Paste both the publishable and secret keys into the appropriate fields in the Benecaster settings panel. You can enter both test and live key sets at the same time.

Benecaster validates the key prefixes before saving:

Test publishable key must start with pk_test_
Test secret key must start with sk_test_
Live publishable key must start with pk_live_
Live secret key must start with sk_live_

Keys that fail this check are rejected with an error before any storage. This prevents accidentally saving live keys in the test slot or vice versa.

Secret keys are write-only. Once saved, Benecaster never returns the secret key value — not in page loads, not in REST responses, not anywhere in the admin. The settings panel shows only whether a secret key is saved (✓ Secret key saved), not the key itself. If you need to inspect or rotate a secret key, do so in the Stripe Dashboard.

Publishable keys are shown masked. The panel displays the first eight characters of a saved publishable key followed by … (for example, pk_live_AB12…). This is enough to confirm you’ve entered the right key set without exposing the full value.

Tier provisioning on first save. When a keyset transitions from incomplete (missing either key) to complete (both keys saved), Benecaster automatically sweeps all existing membership tiers and creates the corresponding Stripe Products and Prices for that keyset. This means: if you create tiers before entering your live keys, entering the live keys later will backfill the live Stripe IDs automatically. No manual re-save of each tier is needed.

Step 3: Test the Connection

After saving, click “Test connection”. Benecaster retrieves your Stripe account details and confirms the keys are valid. A successful test shows your Stripe account ID and country. An error shows the Stripe API error message inline.

The status indicator above the key fields updates automatically:

Not connected — no keys saved for the active mode
Test mode — keys saved — test keys saved; test mode is active
Live mode — keys saved — live keys saved; live mode is active

Step 4: Set up a Webhook (Required for Live Mode)

Stripe sends subscription lifecycle events (payment failures, cancellations, renewals) to your site via webhook. Without a webhook, Benecaster cannot update subscription status automatically.

The Webhook URL shown in the panel is the endpoint to register in Stripe:

In Stripe Dashboard, go to Developers → Webhooks → Add endpoint
Paste the Webhook URL from Benecaster
Select these events to listen for:
- customer.subscription.deleted
- customer.subscription.updated
- invoice.paid
- invoice.payment_failed
Save and copy the Signing secret (starts with whsec_)
Paste the signing secret into Benecaster → Settings → Listener Support → Stripe → Webhook secret field

(The webhook secret field is shared between Listener Support Stripe and built-in membership — they use the same webhook endpoint.)

Test Mode Vs. Live Mode

The “Use Stripe test mode” toggle determines which key set Benecaster uses for all operations — the subscribe shortcode, the billing portal, and webhook processing.

In test mode, you can use Stripe’s test card numbers to simulate payments without real charges. Test subscriptions and real subscriptions are completely separate — switching from test to live mode does not transfer any subscriptions.

See Payment Test Mode for a full walkthrough of testing your subscription flow before going live.

Staging Sites

If you’re running a staging copy of your site, use test mode keys on staging — never live keys. See Setting Up a Staging Site for the recommended configuration.