Bubble Docs
  • Introduction
  • New? Start Here
  • What is Bubble?
  • The Glossary
  • User manual
    • Getting started
      • What is Bubble?
      • Building your first app
        • Planning features
        • Database structure
        • Design and UX
        • eCommerce and payments
          • Shopping cart
          • Checkout page
          • One-time payments
          • Subscriptions
          • Marketplace
      • Creating and managing apps
      • The Bubble editor
        • Tabs and sections
          • Design tab
            • The element tree
            • The property editor
          • Workflow tab
          • Data tab
          • Styles tab
          • Plugins tab
          • Settings tab
            • Application settings
              • Custom headers/body
              • Visual settings
              • Social media sharing
              • Translating your app
              • Email settings
              • Collaboration
            • Custom domain and DNS
          • Logs tab
        • Tools
          • Key features
          • The search tool
          • The Issue Checker
          • The element tree
          • The element property editor
          • The debugger
          • Notes
        • Previewing your app
      • Transitioning to Bubble from...
        • JavaScript
        • HTML and CSS
        • SQL
    • Design
      • Elements
        • The element hierarchy
          • The element tree
        • The page
        • Containers
          • Groups
          • Repeating groups
          • Table elements
          • Popups
          • Floating groups
          • Group focus
        • Visual elements
        • Input forms
          • Text and numbers
          • Dates and time
          • File uploads
          • Selection controls
        • Reusable Elements
      • Styling
        • Color variables
        • Font variables
        • Styles
        • Custom Fonts
      • Responsive design
        • Building responsive pages
        • Legacy articles
          • The Basics (Legacy)
          • Building Responsive Pages (Legacy)
          • Migrating Legacy Pages
          • Tips When Designing (Legacy)
      • Templates
      • The Component Library
      • Importing from Figma
    • Data
      • The database
        • Data types and fields
        • Creating, saving and deleting data
        • Finding data
        • Displaying data
        • Protecting data with privacy rules
        • The database editor
        • Export/import data
          • Exporting data
          • Importing data (CSV)
        • Working with location data
        • Using Algolia
        • Database structure by app type
          • Marketplace Apps
          • Directory & Listings Apps
          • Social Network Apps
          • SaaS Apps
          • Project Management Apps
          • CRM Apps
          • Professional Services Apps
          • On-demand Apps
          • Documentation/ CMS Apps
          • Applicant Tracking System (ATS) Apps
          • Portfolio Apps
          • Gallery Apps
          • Online Store / Ecommerce Apps
          • Blog Apps
          • Messaging App
          • Dashboards
          • Building Block Apps
          • Bubble as a backend
      • Files
      • Images
      • Static data
        • App texts (translations)
        • Option sets
      • Temporary data
        • Custom states
        • URL parameters
      • User accounts
        • Authentication plugins
          • Facebook plugin
          • Fitbit plugin
          • Google plugin
          • Instagram plugin
          • LinkedIn plugin
          • Pinterest plugin
          • Slack plugin
          • Wistia plugin
          • YouTube plugin
        • Cookies set by Bubble
      • Time, dates and time zones
    • Logic
      • The frontend and backend
      • Workflows
        • Events
          • Frontend events
            • Recurring workflows
            • Custom events
          • Backend events
            • Database trigger events
        • Actions
        • API Workflows
      • Dynamic expressions
      • Conditions
      • Navigation
        • Single-page applications (SPA)
        • Multi-page applications
        • Page slugs
    • Workload
      • Understanding workload
        • Activity types
        • The workload calculation
        • Client-side and server-side processing
      • Tracking workload
        • Measuring
          • Using App Metrics
        • Monitoring
          • Workload notifications
          • Infinite recursion protection
      • Optimizing workload
        • Optimization framework
        • Optimization checklist
          • Page load
          • Searches
          • Workflows and actions
          • Backend workflows
        • Agency showcases
          • Minimum Studio
          • Neam
          • Support Dept
    • Security
      • Bubble's security features
      • Planning app security
      • Client-side and server-side
      • Bubble account security
      • App security
      • Page security
      • Database security
      • API security
        • API Connector security
        • Data API security
        • Workflow API security
      • Flusk
        • Overview
        • Flusk plan features
        • Getting started with Flusk
        • Flusk security tools
          • The Issues Explorer
          • Issue details
          • Tools and settings
            • Pages rating
            • Database rating
        • Flusk FAQ
      • Cookies
      • Security checklist
    • Publishing your app
      • Web app
      • Native mobile app
        • Global native mobile settings
        • iOS App Store
        • Google Play Store
        • Publishing FAQ
    • AI
      • Generate apps with AI
        • About AI app generation
      • AI page designer
      • Connect to AI agents
    • Maintenance
      • Collaborators
      • Version control
        • Best practices: Version control
        • Transitioning from the legacy version control
        • Terminology: Version control
        • Version Control (legacy)
      • Commenting
      • Database maintenance
        • Copying the database
        • Restoring database backups
        • Bulk operations
          • Bulk operation methods compared
        • Wiping change history
      • Performance
        • Hard limits
        • Capacity Usage (legacy)
        • Notes on queries
      • SEO
        • Introduction to SEO
        • SEO: App
        • SEO: Page
      • Testing and debugging
        • Introduction to testing and debugging
        • The debugger
        • The server logs
        • Supported browsers
      • API workflow scheduler
    • Integrations
      • API
        • Introduction to APIs
          • What is a RESTful API?
        • The Bubble API
          • Bubble API terminology
          • Authentication
            • How to authenticate
            • No authentication
            • As a User
            • As an admin
          • The Data API
            • Data API Privacy Rules
            • Data API endpoints
            • Data API requests
          • The Workflow API
            • Workflow API privacy rules
            • Workflow API endpoints
            • API workflows
              • Creating API workflows
              • Scheduling API workflows
              • Recursive API workflows
              • API Workflow Scheduler
              • Case: Stripe notifications
        • The API Connector
          • Authentication
          • API Connector security
          • API guides
            • OpenAI
              • Authentication
              • Calls
                • ChatGPT
                  • Chat
            • Google Translate
              • How to setup Google API keys
          • Streaming API
        • API security
        • Plugins that connect to APIs
        • API Glossary
      • Plugins
        • What Plugins Can Do
        • Installing and using Plugins
        • Authentication plugins
        • Special Plugins
      • SQL Database Connector
      • Bubble App Connector
      • WorkOS
        • WorkOS SSO
        • WorkOS API
    • Infrastructure
      • Sub-apps
      • Bubble release tiers
      • Hosting and scaling
        • How Bubble hosting works
        • Scaling with Bubble
        • CDN (Cloudflare)
        • Bubble app names
        • Domain and DNS
      • Compliance
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks and standards
    • Bubble for Enterprise
      • Hosting and infrastructure
        • Dedicated instance
          • The Dedicated editor experience
          • Technical specs
          • Main cluster dependencies
          • Customizable options
          • Migration process
            • Pre-migration
            • During migration
            • Post-migration
      • Security and compliance
        • Single sign-on (SSO)
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks
        • Bubble's security features
      • Admin and collaboration
      • Priority support
      • Billing and Payment Guideline for Dedicated Instances
  • Core Reference
    • Using the core reference
    • Bubble's Interface
      • Design tab
      • Design tab (Legacy)
      • Workflow tab
      • Data tab
      • Styles tab
      • Styles tab (Legacy)
      • Plugins tab
      • Settings tab
      • Logs tab
      • Template tab
      • Toolbar
      • Top and context menu options
      • Deployment and version control
        • Deployment & Version Control Dropdown (legacy)
      • Notes
    • Elements
      • General properties
      • General properties (Legacy)
      • Styling properties
      • Styling Properties (Legacy)
      • Responsive Properties
      • Responsive Properties (Legacy)
      • Conditional formatting
      • States
      • Page Element
        • Page Element (Legacy)
      • Visual Elements
      • Containers
      • Container Layout Types
      • Containers (Legacy)
      • Input Forms
      • Reusable Elements
      • Element Templates (legacy)
    • Workflows
    • Events
      • General events
      • Element events
      • Custom events
      • Recurring event
      • Database trigger event
    • Actions
      • Account
      • Navigation
      • Data (things)
      • Email
      • Element
      • Custom
    • Data
      • Data Sources
      • Operators and comparisons
      • Search
      • Privacy
    • Styles
    • API
      • The Bubble API
        • The Data API
          • Authentication
          • Data API endpoints
          • Data API requests
        • The Workflow API
      • The API Connector
        • Authentication
        • Adding calls
    • Bubble-made Plugins
      • AddtoAny Share Buttons
      • Airtable
      • API Connector
      • Blockspring
      • Box
      • Braintree
      • Bubble App Connector
      • Chart.js
      • Circle Music Player
      • Draggable Elements
      • Dropzone
      • Facebook
      • Fitbit
      • Full Calendar
      • Google
      • Google Analytics
      • Google Optimize
      • Google Places
      • Ionic Elements
      • iTunes
      • Slidebar Menu
      • LinkedIn
      • Localize Translation
      • Mixpanel
      • Mouse & Keyboard Interactions
      • Multiselect Dropdown
      • Progress Bar
      • Rich Text Editor
      • Rich Text Editor (Legacy)
      • Screenshotlayer
      • SelectPDF
      • Slack
      • Segment
      • Slick Slideshow
      • SQL Database Connector
      • Star Rating
      • Stripe
      • Tinder-like Element
      • Twitter
      • YouTube
      • Zapier
    • Application Settings
      • App plan
      • General
      • Domain / email
      • Languages
      • SEO / metatags
      • API
      • Collaboration
      • Sub-apps
      • Versions
  • Account & Marketplace
    • Account and billing
      • Pricing and plans
        • Plans and billing
        • Billing cycle
        • FAQ: Pricing and Workload
      • Account Management
      • Building Apps for Others
      • Selling on the Marketplace
      • Plans & Billing (legacy)
    • Official Bubble Certification
      • Hiring certified developers
    • Building Plugins
      • The Plugin Editor
      • General Settings
      • Updating to Plugin API v4
      • Adding API Connections
      • Building Elements
      • Building Actions
      • Loading Data
      • Publishing and versioning
      • Github Integration
    • Building Templates
    • Application and data ownership
    • Marketplace policies
    • Bug reports
  • Vulnerability Disclosure Policy
  • Beta features
    • About the Beta features section
    • Native mobile apps 🔒
      • Introduction
        • What is a native mobile app?
        • Native mobile vs. web development
        • Differences in native and web elements
        • Native mobile app terminology
      • Building
        • Views and navigation
        • Native mobile actions
        • Components and gestures
        • Device resources
          • Location services
          • Camera/photo library
      • Previewing
      • Publishing
Powered by GitBook
On this page
  • Defining one-time payments
  • Planning one-time payments
  • Product cost
  • Multiple products
  • Shipping costs
  • VAT/Sales tax (GST compliance)
  • Import tax
  • Common pitfalls with one-time payments
  • Managing one-time payments in Stripe in your Bubble app
  • Charging a user
  • Confirming the payment in your app
  • Refunding a payment
  • FAQ: Using Stripe checkout in your Bubble app
  • Other ways to learn

Was this helpful?

  1. User manual
  2. Getting started
  3. Building your first app
  4. eCommerce and payments

One-time payments

Last updated 2 days ago

Was this helpful?

Disclaimer: Note that while Stripe is mentioned in this document as an example of a payment platform, this should not be interpreted as an endorsement or recommendation of Stripe's services. The information provided here does not constitute legal advice. As an app builder, it is your responsibility to select a payment platform that meets your specific needs. You are also responsible for ensuring compliance with the terms and conditions of the chosen payment platform.

We encourage you to conduct thorough research and, if necessary, consult with a legal professional to make an informed decision.

This article outlines how you can use Stripe to accept one-time payments in your Bubble app. If you are looking for information regarding using Stripe to receive payment for the Bubble template and plugin marketplace, see this article.

Defining one-time payments

One-time payments are payments that are made in isolation between two parties, as opposed to or (where a third party is part of the transaction).

Imagine a user (customer) adding a product to a cart, and then completing a payment transaction to pay for it (such as buying and paying for a t-shirt) – this is what we define as a one-time payment. In this article, we'll look into how you can plan for the development of this time of payment solution.

Planning one-time payments

One early point to talk about is the understanding that most purchases, even if it contains multiple cost records, is still completed in one transaction. Let's unwrap what we mean by that: imagine that you have an app where you sell home-made beanies:

Now, of course you will want your customers to pay for the product when they buy it. But wait – there may be other costs associated with this:

  • Shipping

  • Multiple products

  • VAT/Sales tax

  • Import tax

Before we explore these common cost details, we'll look into the point we just made: even if there are multiple cost items, such as shipping, VAT/taxes and import tax, your users will not pay three times; they'll usually still pay only once.

This may sound obvious, but the underlying point is that you'll need to structure and design your app to take these costs into account, and then prepare that total cost for the payment gateway. We'll cover the costs one-by-one.

We are using Stripe in this example, as it offers features that can handle parts of the collection of different cost items.

Cost
Possible handling

Product

The app sets the cost and sends it to the payment platform.

Multiple products

The app calculates the total cost and sends it to the payment platform

Shipping cost

The app calculates the total cost and sends it to the payment platform

VAT/Sales tax

Stripe offers tools to help businesses handle and sales tax.

Import tax

The app calculates imports tax and adds it to the total amount.

Product cost

The product cost is set/calculated by your app. In other words, Stripe will not have any say in the cost of the product and it's your responsibility to send the correct value through the plugin/API.

Multiple products

Many apps give their users the opportunity to buy more than one product at once. When you plan your app, there are two ways to set this up:

  • Selecting an item quantity: you can include a number in the final checkout that allows users to specify the number of beanies they want to buy

  • Offering a shopping cart: Alternatively, you can offer a shopping cart that users can add items to. This allows greater freedom, such as buying different products.

However you choose to design your app, this kind of setup does not affect Stripe's handling of the total amount: you will still be sending one total sum, regardless of the number of items.

Shipping costs

If you are selling physical products, it's common to ask the users to cover the shipping costs. This can be a simple, set cost, or a dynamic cost based on the number of products, weight, destination address and other details that are relevant.

Again, this is a data point that your app will handle. Stripe does not calculate shipping cost, or consider it separate from the total cost. In other words, whatever your users pay for shipping (if anything), you will only send the total amount to Stripe.

VAT/Sales tax (GST compliance)

In many countries, products and services are subject to VAT (Value Added Tax) or sales tax, and this tax is typically calculated based on the location of the user or customer rather than the seller's location. VAT rates can differ based on various factors, including the type of product or service, whether the purchaser is a business or an individual, and the specific geographical region.

Collecting VAT and sales tax, especially if you sell to a global audience, can be somewhat complex to understand and calculate correctly, and some payment gateways (like Stripe) offer tools to simplify this process. These tools are designed to automatically calculate and collect the appropriate amount of tax on transactions, based on the location of the business and its customers.

You can read more about the tools that Stripe offers on the page below:

External page: Sales tax, VAT, and GST compliance | Stripe Docs

Import tax

Many countries impose an import tax on products brought into their borders. The specific rates and regulations governing this tax differ significantly from one country to another. While apps and online retailers are normally not legally required to collect import tax, some opt to do so as a value-added service. By including import taxes in the total cost at the point of sale, these businesses provide customers with transparent pricing, helping them understand the full cost upfront. This approach can enhance customer experience by preventing unexpected charges upon product delivery.

As highlighted above, the total cost of any online purchase often involves a combination of various charges. These can include the base price of the product or service, applicable VAT or sales tax based on the customer's location, potentially import taxes for international purchases, and sometimes additional fees like shipping or handling.

Common pitfalls with one-time payments

Planning your payment and total cost structure is an important part of creating a viable business. Unrealistic calculations or overlooking associated costs can distort your perception of revenue potential and create a false sense of confidence. By thoroughly considering all expenses and factors involved in sales, you can gain a more accurate understanding of your business's financial health and make informed decisions to optimize profitability.

In this section, we’ll go over some common pitfalls in sales planning.

Lacking cost transparency

Failing to provide clear and comprehensive cost breakdowns to users during the checkout process can lead to confusion and dissatisfaction. Ensure that users have full visibility into all applicable costs, including product prices, shipping fees, taxes, and any additional charges, to avoid surprises and build trust.

Getting the price wrong

Setting a low price can help attract customers – and there’s nothing wrong with that strategy. Still, the amount you are giving away may need to be made somewhere else, or you may end up with less revenue or even a loss on a sale.

The same principle applies to products that are overpriced – while fewer sales may be needed to reach a certain revenue target, striking the right balance between markup and sales potential can often lead to better optimization.

Neglecting hidden costs

Overlooking hidden costs, such as transaction fees charged by payment gateways, storage costs, and man-hours, can lead to unexpected expenses. Factor in all potential costs associated with making an order generate a positive net revenue.

Miscalculating shipping costs

Failing to accurately estimate shipping expenses can potentially give you an unwelcome surprise on the cost side. Shipping cost can vary depending on the carrier, the total weight and volume of the shipment and the address it is sent to. If you are selling products where you expect a dynamic shipping cost, you can look into integrating with shipping carriers using the API connector, or set up internal calculations that give a sufficiently accurate estimate.

Missing regulatory compliance

Neglecting to adhere to legal requirements, such as consumer protection laws or tax regulations, can result in costly penalties or legal disputes. Ensuring compliance with relevant regulations is essential to safeguard your business reputation and financial stability.

Managing one-time payments in Stripe in your Bubble app

This article doesn't cover all the technical details of the plugin, but is meant as an introduction to making one-time payments with Stripe. See the core reference entry below for details on the different actions and properties of the Stripe plugin:

Reference: The Stripe plugin

Bubble's official Stripe plugin is well-suited for handling one-time payments. The plugin has built-in features for charging a user immediately, holding a charge. refunding, and more. You will find all the plugin's actions under the Payments section in the action dropdown.

Charging a user

To see an up-to-date demo of what Stripe's checkout page looks like, and how it can be customized, you can use their interactive Checkout developer page below:

External page: Explore Stripe Checkout

Charging a user means to send the amount and other relevant details to Stripe, so that the user can complete a payment. The user will be redirected to Stripe's checkout page, where they can enter the card details. You start the charge process by triggering the user action, and Bubble will proceed as below:

Confirming the payment in your app

As the illustration shows, the final step of the process is redirecting the user back to the page where the initial page where the process was started. Bubble behaves as if the user never left the page, meaning that the workflow that contained the Charge the current user action will continue to run as soon as the user returns to the page.

The plugin connects to Stripe's API, which means that Stripe gets a request from your app, and then sends a response in return. You can use this to verify that the payment was successful, or to display an error message if it wasn't, as well as save any relevant data in your database as needed.

Stripe's response

The following parameters are made available after a charge has been attempted (whether it was successful or not):

  • Amount: The total amount of the transaction.

  • Amount Received (including coupons): The amount received from the customer after applying any discounts or coupons.

  • Application Fee: The fee that you keep (only relevant for using Stripe Connect)

  • Currency: The currency used for the transaction.

  • Charge Id: The unique identifier for the payment charge.

  • Captured: Indicates whether the payment has been successfully captured.

  • Payment intent id: The unique identifier for the payment intent.

  • Order description: Description of the order or item purchased.

  • Email of charged user: The email address of the customer who made the payment.

  • Product name: The name of the product or service purchased.

  • Product image: An image representing the product or service purchased.

  • Statement descriptor: A description that appears on the customer's credit card statement to identify the transaction.

The expandable box above shows the different parameters that are returned to your app after a charge attempt has been made. If the charge was unsuccessful, Stripe will still return parameters. The following key parameters are often a good idea to save, to make it easy to manage the transaction later:

  • Amount (number): this parameters displays the total amount that was captured in the payment. If the payment was successful, this amount should match what you send in the Charge the current user action.

  • Charge ID (text): this is the auto-generated unique ID of the charge in Stripe's records. It's often useful to save this ID in your app's database, so that you are able to refer to it later as needed. For example, if you want to refund a charge, you will need this ID. You cannot set the initial value or change the value of this ID. There's normally no reason to display this value to the user.

  • Captured (yes/no): this parameter, returned as a yes or no, confirms whether the charge was successful or not. You can use this to take any necessary steps depending on the status of the charge, such as alerting the user of its success or failure.

While you may find the other parameters useful too, these three are generally the ones you want to use to continue to build your checkout workflow. By combining them, you can verify the payment and continue communicating to the user the current status of their purchase, as well as save data needed for your own records.

Refunding a payment

The Stripe plugin enables full refunds for a charge. To process partial refunds, you'll need to configure a custom action using the API Connector plugin.

Article series: The API Connector

Sometimes, you'll find it necessary to refund a payment. The Stripe plugin comes with an action to easily refund the full amount in one step:

To refund a payment, the only needed parameter is the Charge ID that was returned when the initial payment was made. A refund may fail under the following circumstances:

Circumstance
Refunding

No refund made before

The full amount will be refunded

Partial refund made before

The remaining amount will be refunded

Full refund made before

Nothing will be refunded

Transaction is

Nothing will be refunded

FAQ: Using Stripe checkout in your Bubble app

Do I need to set up a form to collect card details?

No, it's unnecessary and in fact, it's not recommended. Stripe handles the collection of this information for you in a secure, encrypted manner that complies with regulatory standards. This simplifies the process of accepting payments from customers, as you don't need to ensure compliance yourself. Instead, you can rely on Stripe to manage this aspect securely and efficiently. You should never store information about the user's card in your database or anywhere else.

What happens if the user clicks "Back" without finishing the Stripe checkout process?

If the user has already been redirected to Stripe Checkout, and then clicks back in their browser, the payment will register as failed. See the Confirming the payment section on how to handle this.

When is the money transferred to my account?

The charge from the user's card is made immediately, and the money is transferred to your app's Stripe account. The money will then be sent to the bank account you have specified in your Stripe dashboard. You can read more about setting up your account and payout frequency in the Stripe Docs article below:

External page: Receive Payouts | Stripe Documentation

Other ways to learn

Core reference

Core reference: The Stripe plugin

Video lessons

YouTube: Bubble and Stripe | Recorded webinar

External documentation

Stripe docs

  • How Stripe Checkout works

  • Webhooks

All actions related to Stripe can be found under the Payments section in the action dropdown.
Using the Results of step 1 data source, you can get relevant information from a charge attempt in Stripe. In this example, we are saving the Charge ID.