Stripe Integration Guide

This guide covers everything you need to know to integrate Stripe with BricksMembers, from initial setup to handling subscriptions, one-time purchases, and refunds.

Why Stripe Integration is Special

BricksMembers provides dedicated Stripe support that goes beyond standard webhook handling:

• Automatic signature verification — Uses Stripe’s official Stripe-Signature header for secure webhook authentication
• Customer ID tracking — Stores Stripe customer IDs to reliably identify users across all webhooks
• Easy Mode UI — Simplified webhook mapping interface designed specifically for Stripe
• Automatic refund handling — Correctly removes levels when one-time purchases are refunded
• Webhook queuing — Handles race conditions when webhooks arrive before user creation completes

Prerequisites

• A Stripe account (Sign up here)
• At least one product with a price created in Stripe
• At least one membership level created in BricksMembers
• SSL certificate (HTTPS) for your WordPress site

Step 1: Enable Stripe Authentication

First, configure BricksMembers to use Stripe’s native authentication:

1. Go to BricksMembers → Webhooks
2. In the provider dropdown, select Stripe
3. Click Apply Provider Settings
4. The Authentication Method will be set to Stripe
5. Copy the Webhook URL — you’ll need this for Stripe
6. Click Save Settings (but don’t close the page yet)

Note: When Stripe authentication is selected, BricksMembers automatically creates the database table needed to track Stripe customer IDs. This happens behind the scenes when you save settings.

Step 2: Create a Webhook Endpoint in Stripe

Now configure Stripe to send webhooks to your site:

1. Log in to your Stripe Dashboard
2. Go to Developers → Webhooks (or Webhooks in the Stripe Dashboard sidebar)
3. Click Add endpoint or Create an event destination (label varies by Stripe account; newer accounts may show “Create an event destination”)
4. Paste the Webhook URL you copied from BricksMembers
5. Under Select events to listen to, click Select events
6. Add these events:
   • checkout.session.completed — Links customer ID to user
   • invoice.payment_succeeded — Grants levels for subscriptions and one-time invoices
   • customer.subscription.created — Grants levels for new subscriptions
   • customer.subscription.updated — Handles plan upgrades/downgrades
   • customer.subscription.deleted — Removes levels on cancellation
   • invoice.payment_failed — Handles failed payments
   • charge.refunded — Removes levels when refunded
7. Click Add endpoint

Step 3: Copy the Webhook Signing Secret

After creating the endpoint, you need to copy Stripe’s signing secret:

1. Click on the newly created webhook endpoint in Stripe
2. Under Signing secret, click Reveal
3. Copy the secret (starts with whsec_)
4. Go back to BricksMembers → Webhooks
5. Paste the secret into the Webhook Secret field
6. Click Save Settings

Important: The signing secret is used to verify that webhooks genuinely come from Stripe. Keep it private and never share it.

Step 4: Configure Webhook Field Mapping

BricksMembers provides an “Easy Mode” interface specifically for Stripe that simplifies configuration:

1. Go to BricksMembers → Webhook Mapping
2. You’ll see a simplified interface because Stripe authentication is enabled
3. The blue notice explains: “Stripe mode auto-configures: email extraction, event detection (invoice.payment_succeeded, subscription changes), customer ID storage, and refund handling. Just map your Price IDs below. Switch to Advanced Mode above for custom configurations.”

What’s automatically configured in Easy Mode:

• Email extraction — Looks in customer_details.email, customer_email, and receipt_email
• Customer name — Extracted and split from customer_details.name
• Event detection — Uses the type field to determine add/remove/change actions
• Price ID extraction — Looks in lines.data[*].pricing.price_details.price and similar paths
• Customer ID storage — Automatically stores and uses Stripe customer IDs

Switching to Advanced Mode

If you need to customize the default field mappings:

1. Click Switch to Advanced Mode in the page header
2. All standard webhook mapping fields will be visible
3. Make your customizations
4. Click Save Settings

Your customizations will be preserved even when switching back to Easy Mode.

Step 5: Map Price IDs to Membership Levels

This is the most important step — connecting Stripe products to BricksMembers levels:

Finding Your Stripe Price IDs

1. Go to your Stripe Products
2. Click on a product
3. Under Pricing, find the price you want to map
4. Click on the price to view details
5. Copy the Price ID (starts with price_)

Mapping Prices to Levels

1. In BricksMembers → Webhook Mapping, scroll to User Level Mapping
2. For each membership level, enter the Stripe Price ID
3. Example:
   • Basic Member: price_1ABC123def456
   • Pro Member: price_1XYZ789ghi012
4. Click Save Settings

Tip: Price IDs are more reliable than product names because they never change. Even if you rename a product in Stripe, the Price ID remains the same.

Step 6: Configure Subscription Changes (Optional)

If you offer subscription plans that customers can upgrade or downgrade:

1. Scroll to the Subscription Level Changes card
2. Check the levels that should be replaced when a subscription changes
3. Example: If you have Basic, Pro, and Premium subscription levels, check all three
4. This ensures that upgrading from Basic to Pro removes Basic and adds Pro

Step 7: Test Your Integration

Option A: Use Stripe Test Mode

1. Toggle Test Mode on in your Stripe Dashboard (top-right corner)
2. Create a test webhook endpoint using the same steps above (Test mode has separate webhooks)
3. Make a test purchase using Stripe’s test card number: 4242 4242 4242 4242
4. Use any future expiration date and any CVC

Option B: Send Test Webhooks from Stripe

1. Go to Developers → Webhooks in Stripe
2. Click on your webhook endpoint
3. Click Send test webhook
4. Select an event type (e.g., invoice.payment_succeeded)
5. Click Send test webhook

Verify the Test Worked

1. Go to BricksMembers → Webhook Mapping
2. Check the Last Received Webhook Data sidebar
3. You should see the webhook data with highlighted important fields
4. Check Users in WordPress to verify the test user was created with the correct level

How Stripe Webhooks Work in BricksMembers

Customer ID Tracking

One challenge with Stripe webhooks is that not all events include the customer’s email address. BricksMembers solves this by:

1. When checkout.session.completed arrives (which includes email), BricksMembers creates/finds the user and stores their Stripe customer ID (cus_xxx)
2. Future webhooks that lack email (like invoice.payment_succeeded) use the stored customer ID to find the user
3. This ensures reliable user identification across all webhook types

Webhook Queuing

Sometimes Stripe sends webhooks faster than expected. If a webhook arrives before the user is fully linked:

1. BricksMembers queues the webhook temporarily
2. When the user is linked (via checkout.session.completed), queued webhooks are processed
3. Queued webhooks expire after 7 days if the user is never linked
4. A daily cleanup removes expired queued webhooks

Refund Handling

When a charge.refunded webhook arrives:

• For subscriptions: The refund doesn’t remove the level (subscription deletion handles this)
• For one-time purchases: BricksMembers looks up which level was granted for that charge and removes it

This is possible because BricksMembers stores a mapping of charge IDs to levels when levels are granted.

Event Reference

Here’s what each Stripe event does in BricksMembers:

Event	Action	Notes
checkout.session.completed	Links customer ID	Stores customer ID for future webhooks
invoice.payment_succeeded	Adds level	Primary event for granting access
customer.subscription.created	Adds level	Also grants access (redundant with invoice.payment_succeeded)
customer.subscription.updated	Changes level	Handles upgrades/downgrades
customer.subscription.deleted	Removes level	Handles cancellations
invoice.payment_failed	Removes level	Revokes access on payment failure
charge.refunded	Removes level	Only for one-time purchases

Troubleshooting

Webhook Authentication Failed (403 Error)

Symptoms: Stripe shows webhook delivery failed with 403 error.

Solutions:

1. Verify the Webhook Secret in BricksMembers matches Stripe’s signing secret
2. Ensure you copied the secret exactly (starts with whsec_)
3. Check that Authentication Method is set to Stripe
4. If using test mode, make sure you’re using the test mode signing secret

User Not Created or Level Not Assigned

Solutions:

1. Enable User Creation/Updating in Webhook Mapping
2. Verify the Price ID in your mapping matches the Stripe Price ID exactly
3. Check the Last Received Webhook Data sidebar to see what data was received
4. Look for the highlighted fields like “Price ID → Product Name”

Webhooks Blocked by Firewall

Some hosting providers or security plugins block external webhook requests.

Solutions:

1. Whitelist Stripe’s IP addresses in your firewall
2. Disable security plugins temporarily to test
3. Contact your hosting provider to allow the BricksMembers webhook endpoint

Viewing Stripe’s Webhook Logs

Stripe provides detailed webhook delivery logs:

1. Go to Developers → Webhooks in Stripe
2. Click on your webhook endpoint
3. Click View recent deliveries
4. Click on any delivery to see:
   • Request body (the webhook payload)
   • Response status code
   • Response body
5. Use the Resend button to retry a failed webhook

Best Practices

• Use Price IDs, not product names — Price IDs are unique and immutable
• Test in Stripe test mode first — Before going live, verify everything works with test data
• Keep the signing secret private — Never share it or commit it to version control
• Monitor webhook deliveries — Check Stripe’s webhook logs regularly for failures
• Use Easy Mode — Unless you need custom field mappings, Easy Mode handles everything automatically

Frequently Asked Questions

Do I need to use Stripe Checkout?

No. BricksMembers works with any Stripe integration method — Checkout, Payment Links, Payment Elements, or even API-based integrations. As long as the webhooks are sent, BricksMembers will process them.

Can I use the same webhook endpoint for test and live mode?

No. Stripe requires separate webhook endpoints for test and live mode. Create two endpoints in Stripe, each with their own signing secret.

What if I change my Stripe product prices?

When you create a new price in Stripe, it gets a new Price ID. You’ll need to add the new Price ID to your BricksMembers mappings. Old Price IDs continue to work for existing subscriptions.

Can one Stripe price grant multiple membership levels?

Currently, each Price ID maps to one membership level. If you need to grant multiple levels for one purchase, you can create a single “bundle” level that provides access to all content, or use Stripe metadata combined with Advanced Mode.

How do I test subscription upgrades/downgrades?

1. Create a test subscription in Stripe test mode
2. Go to the subscription in Stripe Dashboard
3. Click Update subscription
4. Change the price
5. This triggers a customer.subscription.updated webhook
6. Verify the user’s level changed in BricksMembers

With this guide, you should have Stripe fully integrated with BricksMembers. If you encounter issues not covered here, enable webhook logging and check both Stripe’s webhook logs and the “Last Received Webhook Data” sidebar for debugging information.