Bubble supports payment processing through the official Stripe plugin or the API Connector for other gateways. This tutorial covers setting up Stripe for one-time and recurring payments, configuring checkout flows with the Stripe.js element, and handling payment confirmation workflows so your app can accept real money from day one.
Overview: Handling Payments in Bubble
This tutorial walks you through integrating payment processing into your Bubble app. We focus on Stripe — the most popular payment gateway for Bubble builders — covering both one-time charges and recurring subscriptions. You will learn how to install the Stripe plugin, configure your keys, build a checkout page, and create workflows that respond to successful or failed payments. This guide is ideal for non-technical founders building SaaS apps, marketplaces, or e-commerce platforms.
Prerequisites
- A Bubble account with an app ready for payment integration
- A Stripe account (sign up at stripe.com)
- Your Stripe test API keys (publishable and secret)
- A page with a product or service to charge for
- Basic familiarity with Bubble workflows
Step-by-step guide
Install and configure the Stripe plugin
Install and configure the Stripe plugin
Go to the Plugins tab in your Bubble editor. Click Add plugins and search for Stripe. Install the official Bubble-maintained Stripe plugin (it is free). Once installed, you will see configuration fields. Paste your Stripe Publishable Key into the Publishable key field and your Stripe Secret Key into the Secret key field. Use your test keys (starting with pk_test_ and sk_test_) while building. You can find these in your Stripe Dashboard under Developers → API keys.
Pro tip: Keep your live keys separate from test keys. Only switch to live keys (pk_live_ and sk_live_) when you are ready to accept real payments.
Expected result: The Stripe plugin is installed and both API keys are saved in the plugin settings.
Add a Stripe Checkout button to your page
Add a Stripe Checkout button to your page
Go to the Design tab and open the page where users will make a payment. Click the + icon in the Element Palette and search for Stripe Checkout. Drag the Stripe Checkout element onto your page — this is a special button that triggers the Stripe payment modal. In its Property Editor, set the Currency (e.g., USD), the Amount in cents (e.g., 2999 for $29.99), and an optional Description. You can make these values dynamic by clicking Insert dynamic data and referencing your product's price from the database.
Pro tip: Stripe amounts are always in the smallest currency unit — cents for USD, pence for GBP. A $50 charge is 5000, not 50.
Expected result: A Stripe Checkout button appears on your page with the correct amount and currency configured.
Create the payment success workflow
Create the payment success workflow
Go to the Workflow tab. You will see an event called Stripe Checkout payment completed (or When Stripe Checkout's payment is completed). Click it to create a new workflow. Add actions to handle a successful payment: Create a new Thing of type Order or Payment with fields like amount, user, date, and Stripe charge ID (available as the workflow event's charge ID). Then add a Navigate action or show a success message to the user using an Alert or by navigating to a confirmation page.
Expected result: When a test payment succeeds, a new record is created in your database and the user sees a confirmation.
Handle payment failures gracefully
Handle payment failures gracefully
Still in the Workflow tab, look for the event Stripe Checkout payment failed. Click it and add actions to show the user a clear error message — use the Alert element or set a Custom State to display an error text like Payment failed. Please check your card details and try again. Log the failure by creating a PaymentError record with fields for the user, timestamp, and error message so you can review failed payments later.
Pro tip: Use Stripe's test card numbers to simulate failures: 4000000000000002 always declines, 4000000000009995 triggers insufficient funds.
Expected result: Failed payments show a user-friendly error message and are logged in your database for review.
Set up recurring subscription payments
Set up recurring subscription payments
For subscriptions, go back to the Plugins tab and open your Stripe plugin settings. Enable the Subscription features. Then in the Stripe Dashboard, go to Products and create a Product with a recurring Price (e.g., $29/month). Copy the Price ID (starts with price_). In your Bubble workflow, use the Stripe action Subscribe the user to a plan and paste the Price ID. Create a Subscription data type in your database to store the user, plan, status, and Stripe subscription ID. Update this record when the subscription event fires.
Expected result: Users can subscribe to a recurring plan and their subscription status is stored in your database.
Test your entire payment flow
Test your entire payment flow
Make sure you are using Stripe test keys. Open your app in Preview mode. Click the Stripe Checkout button. In the Stripe modal, use the test card number 4242 4242 4242 4242 with any future expiry date and any CVC. Complete the payment and verify that your success workflow runs — check the database for the new Payment or Order record. Also test a decline using 4000000000000002 and confirm your error handling works. Check your Stripe Dashboard → Payments to see the test transactions.
Pro tip: When you are ready to go live, switch both Stripe keys to their live versions and deploy your app to Live. For complex payment setups like marketplaces or multi-currency billing, consider reaching out to RapidDev for expert Bubble development support.
Expected result: Test payments succeed and fail correctly, records are created in the database, and transactions appear in the Stripe Dashboard.
Complete working example
1PAYMENT FLOW WORKFLOW SUMMARY2==============================34PLUGIN SETUP:5 Plugins tab → Add plugins → Stripe6 Publishable key: pk_test_xxxx7 Secret key: sk_test_xxxx89DATA TYPES:10 Payment11 - amount (number)12 - currency (text)13 - user (User)14 - stripe_charge_id (text)15 - status (text: succeeded / failed)16 - created_date (date)1718 Subscription19 - user (User)20 - stripe_subscription_id (text)21 - plan_name (text)22 - price_id (text)23 - status (text: active / canceled / past_due)24 - current_period_end (date)2526PAGE ELEMENTS:27 - Stripe Checkout element28 Currency: USD29 Amount: dynamic (Current Page Product's price * 100)30 Description: dynamic (Current Page Product's name)3132WORKFLOW 1: Payment Success33 Event: Stripe Checkout payment completed34 Action 1: Create a new Payment35 amount = Stripe Checkout's amount / 10036 currency = USD37 user = Current User38 stripe_charge_id = Stripe Checkout's charge ID39 status = succeeded40 Action 2: Navigate to page confirmation41 Send: Result of Step 14243WORKFLOW 2: Payment Failure44 Event: Stripe Checkout payment failed45 Action 1: Show Alert "Payment failed. Please try again."46 Action 2: Create a new Payment47 amount = Stripe Checkout's amount / 10048 user = Current User49 status = failed5051WORKFLOW 3: Subscription52 Event: Button Subscribe is clicked53 Action 1: Subscribe the user to a plan54 Price ID: price_xxxx55 Action 2: Create a new Subscription56 user = Current User57 stripe_subscription_id = Result of Step 1's ID58 plan_name = Pro Plan59 status = active6061TEST CARDS:62 Success: 4242 4242 4242 424263 Decline: 4000 0000 0000 000264 Insufficient: 4000 0000 0000 9995Common mistakes when handling payments in Bubble
Why it's a problem: Using live Stripe keys during development
How to avoid: Always use test keys (pk_test_ and sk_test_) during development. Switch to live keys only when deploying to production.
Why it's a problem: Entering the payment amount in dollars instead of cents
How to avoid: Multiply your dollar amount by 100 before passing it to the Stripe Checkout element. Use a dynamic expression like Product's price * 100.
Why it's a problem: Not storing the Stripe charge or subscription ID in the database
How to avoid: Always save the charge ID or subscription ID returned by the Stripe event into a field in your Payment or Subscription data type.
Why it's a problem: Forgetting to handle payment failure events
How to avoid: Create a workflow for the payment failed event that shows a clear error message and logs the failure.
Best practices
- Always use Stripe test keys during development and switch to live keys only at deployment
- Store every Stripe charge ID and subscription ID in your database for future reference and refunds
- Show clear confirmation messages on payment success and helpful error messages on failure
- Use Stripe's test card numbers to simulate all scenarios: success, decline, insufficient funds, and expired card
- Set up Privacy Rules on your Payment data type so users can only see their own payments
- For subscription apps, create a backend workflow triggered by Stripe webhooks to handle subscription status changes
- Display prices including currency symbol and format them consistently across your app
- Log all payment events in a separate data type for auditing and troubleshooting
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I am building a Bubble.io app and need to accept payments via Stripe. My app sells [describe product/service] with prices starting at [price]. I need both one-time payments and monthly subscriptions. Can you outline the data types, page elements, and workflows I need to set up?
Help me add Stripe payment processing to my app. I need a checkout page where users can pay for a product, a success confirmation page, and a way to track all payments in my database. Set up both one-time and subscription payment workflows.
Frequently asked questions
Which Stripe plugin should I use in Bubble?
Use the official Stripe plugin maintained by Bubble. It is free and supports Checkout, subscriptions, and basic payment flows. For advanced needs like Connect or metered billing, you may need the API Connector.
Can I accept payments on Bubble's free plan?
You can build and test payment flows on the free plan, but you cannot deploy to a live URL. You need at least the Starter plan to publish a live app that accepts real payments.
How do I handle refunds in Bubble?
Refunds are processed in the Stripe Dashboard or via the API Connector calling Stripe's Refund endpoint. Store the Stripe charge ID in your database so you can easily find the transaction to refund.
Can I use PayPal instead of Stripe in Bubble?
Yes. You can integrate PayPal using the API Connector plugin to call PayPal's REST API, or use a community PayPal plugin from the Bubble marketplace. Stripe is more commonly used due to better plugin support.
How do I test payments without using a real credit card?
Use Stripe test mode with test API keys. Stripe provides test card numbers like 4242 4242 4242 4242 for successful payments and 4000000000000002 for declines. No real money is charged in test mode.
Is it safe to put Stripe keys in Bubble?
Yes. The publishable key is safe for client-side use. The secret key is stored in the plugin settings and Bubble keeps it server-side — it is never exposed to the browser. Never put your secret key in a visible element or URL parameter.
Can RapidDev help with complex payment integrations?
Yes. RapidDev specializes in Bubble development and can help with advanced payment flows like marketplace payouts with Stripe Connect, subscription billing with usage metering, and multi-currency support.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation