Skip to main content

Connecting Stripe for Subscriptions

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

There are two ways to set this up, and which one you want depends on where the money should land:

  • One Stripe account for the whole site. The usual case. Connect it once and every show uses it.
  • A different Stripe account for a particular show. For a show whose income belongs to someone else — a co-owned show, a show you produce for a client. You can mix the two freely, and you can run this way with no site-wide account at all.

Both are covered below. Start with the site-wide connection unless every one of your shows belongs to a different account.

The Two Site-Wide Panels

Stripe keys appear in two places in the admin:

  • Settings → Payments — the main panel. Test and live key sets, the test-mode toggle, the webhook secret, and a connection test.
  • Settings → Listener Support — the donations panel. One key pair and a webhook secret.

These edit the same keys. Saving in one is reflected in the other. There is one Stripe key store for the site, and both panels write to it.

The difference is what each panel shows you. The Payments tab (its heading reads Membership → Payments) shows both key sets — test and live — side by side, and is the only place to switch which one is active. Listener Support shows a single pair: whichever set is currently active. It says so on screen, and points you back to Membership → Payments to switch modes.

Where to Find It

Benecaster → Settings → Payments

The panel shows two key sets — Test keys and Live keys — with a “Use Stripe test mode” toggle above them, a Webhook section below, and Save settings and Test connection buttons at the bottom.

Step 1: Get Your Stripe API Keys

See Your Stripe Account and API Keys for the Stripe-side walkthrough — account setup, retrieving keys, test cards, and the test-to-live switch. The short version:

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. You can enter both test and live key sets at the same time, and each is saved independently — filling in your live keys does not disturb your test keys.

Benecaster checks 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_

A key in the wrong slot is refused, and nothing is saved. This is the check that stops a live key ending up in the test slot, which would mean charging real cards from a test environment.

Secret keys are write-only. Once saved, Benecaster never shows a secret key again — not on the settings screen, not anywhere in the admin. The field’s label reads “saved — leave blank to keep current”, so leaving it empty on your next save keeps the key you already have. To change a secret key, paste the new one over it. To inspect or rotate one, use the Stripe Dashboard.

To remove a saved key rather than replace it, use the Clear control. Any mode with keys saved shows Clear test keys or Clear live keys, here and on a show’s own Payments tab. It confirms before acting, then removes both keys for that mode. There is no undo — the secret is encrypted and not recoverable from Benecaster, so you would be copying it from Stripe again. The other mode is unaffected.

Do not confuse the two. A blank secret field on save keeps the existing key; only the Clear control removes it. Disconnecting an account has never required WP-CLI or database access.

Tier provisioning on first save. When a key set goes from incomplete (missing either key) to complete, Benecaster sweeps your active paid tiers and creates the matching Stripe Products and Prices for that key set. So if you create tiers before entering your live keys, entering the live keys later backfills the live Stripe IDs automatically — no need to re-save each tier. The sweep is per tier, not per site, so a tier belonging to a show on its own Stripe account is provisioned into that show’s account.

The sweep fills only what is missing. If a tier already holds Stripe IDs for a mode and you point that mode at a different Stripe account, the old account’s IDs remain and are not re-minted — and they do not exist in the new account, so checkout fails against them. Clear the affected tiers’ Stripe IDs when you move a mode to a different account.

Buy-ups are not included in the sweep. Episode buy-ups are provisioned when the buy-up is created or edited. Re-save any existing buy-ups after adding a key set. See Switching to Live Mode.

Step 3: Test the Connection

After saving, click Test connection. Benecaster retrieves your Stripe account details and confirms the keys work. Success reports your Stripe account ID and country — check them, because they are how you confirm you connected the account you meant to rather than merely a valid one. A failure shows Stripe’s own error message inline.

The status indicator above the key fields reads:

  • 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, refunds — to your site by webhook. Without one, Benecaster cannot keep subscription status up to date.

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

  1. In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint
  2. Paste the Webhook URL from Benecaster
  3. Select these eight events (the setup wizard lists the same eight):
    • customer.subscription.updated
    • customer.subscription.deleted
    • customer.updated — optional, and only matters if you collect sales tax. When Stripe could not work out where a subscriber is, it lets Benecaster put tax back on their subscription as soon as they fix their address. Without it, Benecaster checks once a day instead.
    • invoice.paid
    • invoice.payment_failed
    • charge.refunded — records a refund against your revenue. Without it, a refund made in Stripe is never recorded and the money keeps counting as revenue.
    • payment_intent.succeeded — Stripe donations
    • payment_intent.payment_failed — Stripe donations, and the warning Benecaster shows when too many donation attempts are declined
  4. Save, and copy the Signing secret (starts with whsec_)
  5. Paste it into the Webhook signing secret field in this same panel, and save

Both site-wide panels have a webhook secret field, and both write the same one. There is one site-wide endpoint and one signing secret.

An endpoint that is missing an event keeps working for everything else, so nothing visibly breaks. To add one to an existing endpoint, open it in Stripe under Developers → Webhooks, choose to add events, and select the missing ones. You don’t need a new endpoint or a new signing secret.

The webhook check

Once a day, Benecaster reads the webhook endpoints on each show’s live Stripe account and shows an admin notice for that show when:

  • no endpoint points at this site’s webhook URL (or, for a show on its own Stripe account, that show’s own URL);
  • every endpoint that does point here is disabled; or
  • the endpoint is missing an event the show needs. A show on built-in membership needs customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed and charge.refunded. A show taking donations through Stripe needs payment_intent.succeeded and payment_intent.payment_failed. The check never asks for the optional customer.updated.

The notice names the problem and links to Stripe’s webhooks page. Once you have fixed the endpoint, the notice clears itself at the next daily check. Test mode is never checked: local testing usually runs through the Stripe CLI, which registers no endpoint.

A Different Stripe Account for One Show

Shows → [show] → Settings → Payments

Use this when a show’s income belongs somewhere other than your main account. The tab governs everything Benecaster charges for on that show — donations, subscriptions, buy-ups, and the Products and Prices Benecaster creates in Stripe. It is not a donations-only setting.

The tab opens by telling you which account the show is on and which mode is active, before any editable field, so you can answer “where is this show’s money going?” without reading the form.

To move a show onto its own account:

  1. Tick Use a different Stripe account for this show
  2. Enter that account’s test and live keys. Same prefix rules as the site-wide panel; the key set currently in use is labelled so you can tell them apart
  3. Register that show’s webhook URL — see below
  4. Save payment settings, then Test connection. The result names which account answered, this show’s own account or the site-wide account, which is what distinguishes configured from configured correctly

To move it back: untick the box and save. This clears every key you entered for that show — both modes and its webhook secret — and the show returns to the site-wide account. Nothing else about the show changes.

Each show needs its own webhook endpoint. Each Stripe account signs events with its own secret, so a show on a different account cannot use the site-wide endpoint. The tab shows that show’s URL, with a Copy button:

https://yoursite.com/wp-json/benecaster/v1/stripe-webhook/{show-uuid}

Register that URL in that Stripe account, and paste the signing secret it gives you into the tab. Registering the site-wide URL in a different Stripe account produces events that can never verify — which looks exactly like a broken integration, with no error pointing at the cause.

A show that has no keys of its own keeps using the site-wide endpoint and secret. The per-show URL only matters once the show overrides.

Setting this show’s test or live mode

A show on its own Stripe account has its own Test or live control on this tab, with three options:

  • Follow the site default — the tab tells you which that currently is
  • Test — this show does not take real money
  • Live — this show takes real money

Changing it affects only this show. Other shows keep their own setting, and shows following the site default are unchanged. This is what lets you rehearse a new show against test keys while your existing shows keep billing real cards — see Test Mode.

On a show using the site-wide account the control is disabled, and that is not an oversight. Such a show has no keys of its own, and the keys themselves are what make an account test or live — there is nothing separate to switch. To give one show its own mode, give it its own Stripe account above; to change what every following show does, use Settings → Payments.

The panel’s (in use) keyset label and the sentence above it describe this show, not the install — so on a show billing through its test keys the test set is the one marked in use, whatever the site default is.

Running With No Site-Wide Account at All

Every show on its own Stripe account, and no site-wide keys, is a supported setup — not a workaround. If your shows have different owners, this is the normal shape rather than an exception, and nothing on the site-wide panel needs filling in.

Built-in membership becomes available as soon as Stripe keys exist anywhere — site-wide or on any single show. You will not be prompted to connect a site-wide account you do not need, and the Listener Support setup reminder stays quiet once at least one show is configured.

The one thing to keep in mind: a show with no keys of its own falls back to the site-wide account, and if there is no site-wide account it has nothing to fall back to. So on this setup, every show that takes money needs its own keys.

Test Mode Vs. Live Mode

The “Use Stripe test mode by default” toggle decides which key set Benecaster uses for everything — the subscribe shortcode, the billing portal, donations, and webhook processing.

It is a default, not a global answer. A show with its own Stripe account can set its own mode and wins over this setting, so “test mode is on” here does not by itself mean nothing on the site is charging. The banner at the top of every Benecaster admin screen is what answers that properly.

In test mode you can use Stripe’s test card numbers to simulate payments without real charges. Test and live subscriptions are entirely separate; switching modes does not transfer anything between them.

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.

See Also

Need this built rather than just documented? See our services →