Paystack with Bubble

Among no-code platforms, Bubble stands out for payment integration because it gives you three things other builders do not:

• JavaScript plugin support. Bubble plugins can include custom JavaScript that runs in the browser. The Paystack plugin uses this to load Paystack's Inline JS and trigger the checkout popup, which other no-code builders (Wix, Webflow) cannot do natively.
• API Connector. Bubble's API Connector lets you call any REST API directly. This means you can call Paystack's transaction verification endpoint, list transactions, query customer data, initiate refunds, and use any Paystack API feature, not just the checkout.
• Database and workflows. After a payment completes, you can update Bubble's database, send emails, trigger other workflows, and manage the complete post-payment business logic without writing code.

This combination means you can build a fairly sophisticated payment flow in Bubble: charge a customer, verify the payment, update their account status, send a confirmation email, and log the transaction, all without writing traditional code.

This guide is part of the Paystack plugins and no-code integrations cluster.

Step 1: Install the plugin. In your Bubble editor, go to Plugins. Search for "Paystack" in the plugin marketplace. Several Paystack plugins may be available. Look for the one with the most installs and recent updates. Install it.

Step 2: Enter your API keys. In the plugin settings, you will see fields for your Public Key and Secret Key. Enter your test keys first. The public key goes in the field marked for client-side use. The secret key goes in the field marked for server-side (API Connector) use.

Step 3: Configure the plugin element. The plugin typically adds a visual element or an action to your Bubble toolbox. Drag the Paystack element onto your page (if it is a visual element) or note the new workflow action available (if it is an action-based plugin).

Step 4: Set up the workflow. Create a workflow triggered by a button click (for example, "Pay Now"). In the workflow, add the Paystack checkout action. Configure the amount (in the smallest currency unit, such as kobo for NGN or cents for KES), the customer email, and any metadata you want to attach to the transaction.

The specifics depend on which Paystack plugin you install. Read the plugin's documentation for the exact configuration steps. The general pattern is always: trigger checkout, handle callback, update database.

A typical Bubble checkout workflow with Paystack looks like this:

Step 1: User clicks "Pay Now." This triggers a Bubble workflow.

Step 2: Workflow triggers Paystack checkout. The Paystack plugin opens the Inline checkout popup. The popup shows the payment form with the amount, customer email, and available payment channels (card, bank transfer, M-Pesa, etc.).

Step 3: Customer completes payment. The customer enters their payment details and completes the transaction on Paystack's secure form.

Step 4: Callback fires. The Paystack plugin triggers a callback event in Bubble with the transaction reference and status. You handle this callback in a separate workflow.

Step 5: Update the database. In the callback workflow, create or update a "Payment" record in your Bubble database with the transaction reference, amount, customer, status, and timestamp.

Step 6: Verify server-side. Use the API Connector to call Paystack's Verify Transaction endpoint with the transaction reference. This confirms that the payment actually happened and the amount matches what you expected. Only after verification should you grant access, update the user's account, or mark the order as paid.

Step 7: Update UI. Show a success message, redirect to a confirmation page, or update the user's dashboard to reflect the payment.

The verification step (Step 6) is critical. Without it, a malicious user could spoof the callback and pretend they paid without actually completing the transaction. See the security section below for more on this.

The Paystack Bubble plugin handles the checkout popup. For everything else, you use Bubble's API Connector to call Paystack's REST API directly.

Setting up the API Connector:

1. Go to Plugins > API Connector in your Bubble editor.
2. Add a new API called "Paystack API."
3. Set the base URL to https://api.paystack.co.
4. Add a shared header: Authorization with value Bearer [your_secret_key]. Mark this as a private/server-side header so it is never exposed to the browser.

Useful API calls to set up:

• Verify Transaction: GET to /transaction/verify/[reference]. Use this after every payment to confirm it is genuine.
• List Transactions: GET to /transaction with query parameters for date range, status, and pagination. Useful for admin dashboards.
• Fetch Customer: GET to /customer/[email_or_code]. Look up a customer's payment history.
• Initiate Refund: POST to /refund with the transaction reference. Use this to process refunds from your Bubble admin panel.
• Create Plan: POST to /plan. Set up subscription plans for recurring billing.

Each API call is configured once in the API Connector and then available as a data source or workflow action throughout your Bubble app. You can display transaction lists in repeating groups, show customer details on profile pages, and trigger refunds from admin buttons.

Bubble handles most of the hosting and infrastructure security, but payment integration introduces responsibilities that Bubble's defaults do not cover.

Never expose your secret key. In the API Connector, make sure the Authorization header containing your secret key is marked as a private/server-side parameter. If it is set as a client-side parameter, it will be visible in the browser's network tab, and anyone can use it to call the Paystack API as your account.

Always verify transactions server-side. The callback from the Paystack checkout popup is client-side. A user can manipulate their browser to fire a fake callback with a fabricated transaction reference. Before granting any value (access, credits, product delivery), call the Verify Transaction API through the API Connector (which runs server-side) to confirm the payment is real and the amount is correct.

Use privacy rules. Bubble's privacy rules control which data is visible to which users. Payment records should only be visible to the user who made the payment and to admin users. Without privacy rules, any authenticated user could query your database and see other users' payment data.

Amount validation. If the payment amount is calculated client-side (for example, based on items in a shopping cart), a user could manipulate the DOM to change the amount before the checkout triggers. Calculate the expected amount in your workflow logic or verify it server-side after payment.

Test mode discipline. Use test API keys during development. Only switch to live keys when your app is deployed and tested. Never use live keys on a development version of your Bubble app.

Marketplace payments. A marketplace app where buyers pay sellers can use Paystack's split payment or subaccount features. Set up each seller as a Paystack subaccount via the API Connector. When a buyer pays, include the subaccount code in the transaction initialization. Paystack splits the payment between the seller and your platform automatically.

Subscription billing. Create Paystack Plans via the API Connector. When a user subscribes, use the Paystack subscription API to set up recurring charges. Store the subscription code in your Bubble database. Use the API Connector to check subscription status, handle renewals, and process cancellations.

Course or membership access. After payment verification, update the user's record in Bubble to grant access to premium content. Use Bubble's page access rules or conditional visibility to show premium content only to users who have a verified payment record.

Invoice payments. Generate an invoice in your Bubble app, calculate the amount, and trigger a Paystack checkout with the invoice total. After payment, link the Paystack transaction reference to the invoice record and mark it as paid.

Bubble's flexibility means you can implement most payment patterns without touching code. The limit is usually in the complexity of the Paystack API call, not in Bubble's ability to make the call.

Checkout popup does not appear. Check that the plugin is installed and the public key is correctly entered. Check the browser console for JavaScript errors. Common causes: an ad blocker blocking the Paystack script, a Content Security Policy header on your Bubble app blocking external scripts, or a conflict with another plugin.

Callback does not fire after payment. Some Paystack Bubble plugins have specific requirements for how the callback event is handled. Check the plugin's documentation. Make sure you have a workflow set up that listens for the plugin's callback event, not a generic event.

Amount mismatch. Paystack expects amounts in the smallest currency unit (kobo for NGN, cents for KES). If your Bubble app sends the amount in naira or shillings instead of kobo or cents, the customer will be charged 100x the intended amount. Always multiply by 100 before sending to Paystack.

API Connector returning errors. If the Verify Transaction or other API calls fail, check that your secret key is correct and that the Authorization header format is exactly Bearer sk_test_xxxxx (with a space after "Bearer"). Also check that the API call URL is correct and that the parameters are in the right format.

Privacy rule conflicts. If your verification workflow cannot read the payment record it just created, your privacy rules may be too restrictive. Make sure backend workflows have the necessary permissions to read and write payment records.