Skip to content

Testing your integration

Generated from the canonical integration guide

This page is generated from docs/integration/testing.md — the single source of truth shared with the public marketing site. Edit the canonical file, then run npm --prefix tools/integration-docs-derive run derive.

Test the full subscribe → charge flow end to end without moving real money using Stripe test mode. This is the fastest way to validate your integration — Stripe test mode works on any store, with no BigCommerce sandbox required.

How test mode works

bc-subscriptions has no separate test/live toggle. The mode is determined entirely by the Stripe key you connect:

  • A test secret key (sk_test_…) routes every charge to Stripe's sandbox.
  • A live secret key (sk_live_…) charges real cards.

So "test mode" just means connect a test key. Switching to production is a key swap — no code changes. (See the Stripe adapter contract in apps/api/src/adapters/stripe.ts.)

Card data never touches bc-subscriptions in either mode — it goes directly to Stripe, which returns a token used for all future charges (see ADR-0037).

Walkthrough

  1. Connect Stripe with test keys. In the admin, follow processor onboarding and paste your Stripe test secret + publishable keys (sk_test_… / pk_test_…). Grab them from the Stripe Dashboard → API keys.
  2. Render a subscribe button. Wire up your storefront per your tier — Catalyst, headless, or Stencil. Confirm at least one plan exists (see Before you start).
  3. Subscribe with a test card. At payment entry use Stripe's success card:
Card:   4242 4242 4242 4242
Expiry: any future date (e.g. 12/34)
CVC:    any 3 digits
ZIP:    any value

This creates a subscription and fires a test PaymentIntent charge. 4. Verify. The subscription appears in the subscriber portal and the merchant dashboard; the charge shows in your test-mode Stripe Dashboard → Payments. Cross-check the charge record via the API reference (GET /api/v1/portal/subscriptions/{id}/charges). 5. Exercise decline + dunning. Use a Stripe declined-payments test card to trigger a failed renewal and watch the dunning/retry flow run. 6. Exercise SCA / 3DS. Use Stripe's regulatory (3D Secure) test cards to confirm your integration handles authentication challenges.

Webhook events while testing

Subscription lifecycle events (charge succeeded/failed, subscription paused/cancelled, etc.) fire the same in test mode. The authoritative event names + payloads are in the API reference — see the webhooks tag. Point your test webhook endpoint at a tunnel (e.g. a local HTTPS tunnel) to inspect them during development.

Going live

Replace the test keys with live keys (sk_live_… / pk_live_…) in processor onboarding. No integration code changes are needed — the key prefix is the only difference between test and live.

Reference