Bubble.io Stripe Integration: The Step-by-Step Guide to Accepting Payments
One-time payments, recurring subscriptions, the Customer Portal, and webhooks — every Stripe scenario in Bubble with every API call shown. The most complete Bubble + Stripe guide available.
Stripe + Bubble: The Most Searched Integration in No-Code
Charging money is the moment an app becomes a business, which is why Stripe is one of the most common integrations in Bubble.io. This guide covers the main scenarios step by step: one-time payments, recurring subscriptions, the Customer Portal for self-serve billing, and the webhooks that keep your app in sync with Stripe, plus how to secure those webhooks. For marketplaces, see the Stripe Connect section below.
Setting Up the Stripe API Connector
Authentication: Private key in header
Key: Authorization
Value: Bearer sk_live_XXXXX (mark as private)
// Use sk_test_XXXXX during development
// Switch to sk_live_XXXXX before going live
// Never expose your secret key to the browser
mode = “payment”
line_items[0][price] = “price_XXXXX” (your Stripe Price ID)
line_items[0][quantity] = 1
success_url = “https://yourapp.com/success?session={CHECKOUT_SESSION_ID}”
cancel_url = “https://yourapp.com/pricing”
customer_email = Current User’s email
// Response: url → navigate user to response’s url
mode = “subscription”
customer = Workspace’s stripe_customer_id
client_reference_id = Workspace’s Unique ID
metadata[workspace_id] = Workspace’s Unique ID
line_items[0][price] = Plan’s stripe_price_id
subscription_data[metadata][workspace_id] = Workspace’s Unique ID
subscription_data[trial_period_days] = Plan’s trial_days
success_url = “https://yourapp.com/billing/success”
// NEVER trust success_url to activate subscription
// Only webhooks are authoritative for billing state
customer = Workspace’s stripe_customer_id
return_url = “https://yourapp.com/billing”
// Navigate user to response’s url
// Customer can: update card, view invoices, change plan, cancel
// No custom UI to build — Stripe hosts the portal
Handling Stripe Webhooks in Bubble
// URL will be: https://yourapp.bubbleapps.io/api/1.1/wf/stripe_webhook
// 2. In Stripe Dashboard → Developers → Webhooks → Add endpoint
// Paste your Bubble workflow URL
// Select events: checkout.session.completed, customer.subscription.updated,
// customer.subscription.deleted, invoice.payment_failed,
// invoice.payment_succeeded, customer.subscription.trial_will_end
// 3. Webhook handler workflow (Step 1)
Extract workspace_id:
checkout.session.completed: Trigger data’s object’s client_reference_id
customer.subscription.* events: Trigger data’s object’s metadata’s workspace_id
// Checkout Session and Subscription are different objects,
// so read the ID from the object each event actually sends
Find Workspace:
Search for Workspaces [Unique ID = workspace_id] :first item
Update Workspace based on event type:
checkout.session.completed → subscription_status = Active
invoice.payment_failed → subscription_status = Past Due
subscription.deleted → subscription_status = Cancelled
Test Webhooks With Stripe CLI Before Going Live
Install the Stripe CLI and run stripe listen –forward-to [your Bubble webhook URL] to forward test events to your development app. Then trigger events with stripe trigger checkout.session.completed. Testing webhooks locally prevents billing bugs from reaching production customers.
Securing Your Stripe Webhook in Bubble
A Bubble backend workflow exposed as an API endpoint is public: anyone who knows the URL can send it data. Without protection, someone could post a fake “payment succeeded” event and unlock a paid plan. Stripe signs every webhook, but checking that signature inside a standard Bubble workflow is not straightforward, so use one of these approaches:
-
✓
Re-fetch the event from Stripe. Take only the event ID from the incoming webhook, then call Stripe’s API (GET /v1/events/{id}) with your secret key and act on what Stripe returns. A forged event will not exist in your Stripe account.
-
✓
Verify the signature outside Bubble. Receive the webhook in a small external function or automation that verifies Stripe’s signature, then forwards trusted events to Bubble.
-
✓
Make handlers idempotent. Stripe can send the same event more than once, so store processed event IDs and skip duplicates.
-
✓
Use the right URL for each version. Your development version’s endpoint includes /version-test/, so register separate test and live webhooks in Stripe.
Stripe Connect for Bubble Marketplaces
If your app takes payments on behalf of sellers or service providers, such as a marketplace or booking platform, you need Stripe Connect rather than standard payments. Connect handles seller onboarding and identity checks, splits each payment between the seller and your platform fee, and pays sellers out to their bank accounts. It adds onboarding flows, account states and extra webhooks to your app, so plan it carefully. Our Bubble.io Stripe Connect guide walks through the setup.
Stripe Plugin or API Connector?
Bubble’s official Stripe plugin is the quickest way to take simple payments and subscriptions, with ready-made actions and little setup. The API Connector approach in this guide takes more work but gives you full control over Checkout Sessions, metadata, the Customer Portal and webhooks, which most growing SaaS products need. A sensible rule: start with the plugin for simple one-off payments, and use the API Connector for subscription billing you will need to grow and debug.
Frequently Asked Questions
Can Bubble.io accept Stripe payments?
Yes. Bubble can take one-time payments and subscriptions through Stripe, using either the official Stripe plugin or the API Connector with Stripe Checkout, the Customer Portal and webhooks.
Why is my Bubble subscription not activating after payment?
Usually because the webhook cannot find the right record. A completed Checkout Session and a Subscription are different objects in Stripe, so pass client_reference_id on the session and read it in your checkout.session.completed handler, and make sure the webhook URL matches the live or test version of your app.
Do I need webhooks for Stripe in Bubble?
For subscriptions, yes. Renewals, failed payments and cancellations happen in Stripe, not in your app, and webhooks are how your app finds out. Never rely on the success page alone to activate a plan.
How do I secure a Stripe webhook in Bubble?
Treat incoming webhook data as untrusted. Re-fetch the event from Stripe’s API using its ID before acting on it, or verify Stripe’s signature in an external function that forwards trusted events to Bubble.
Ready to Build Your App on Bubble?
Architecture review, data model design, Stripe billing and full builds, done right from day one by a certified Bubble.io developer.