# How to integrate a cryptocurrency payment gateway in Bubble.io: Step-by-Step Gui

- Tool: Bubble
- Difficulty: Beginner
- Time required: 20-25 min
- Compatibility: All Bubble plans (Growth+ recommended for backend workflows)
- Last updated: March 2026

## TL;DR

Accept cryptocurrency payments in your Bubble app by integrating Coinbase Commerce via the API Connector. Create payment charges through the Coinbase Commerce API, redirect users to a hosted checkout page, and verify completed payments through webhook notifications sent to a backend workflow endpoint in your Bubble app.

## Accepting Cryptocurrency Payments in Your Bubble App

Cryptocurrency payments let your app accept Bitcoin, Ethereum, and other digital currencies. This tutorial shows you how to integrate Coinbase Commerce — one of the simplest crypto payment processors — into your Bubble app using the API Connector. Users click a pay button, get redirected to a Coinbase-hosted checkout, and your app receives a webhook when payment is confirmed. No crypto wallet management required on your end.

## Before you start

- A Bubble account with an app open in the editor
- A Coinbase Commerce account (commerce.coinbase.com) with API key
- The API Connector plugin installed
- Backend workflows enabled (Settings → API → enable Workflow API)

## Step-by-step guide

### 1. Configure Coinbase Commerce API in the API Connector

Go to the Plugins tab → API Connector → Add another API. Name it 'CoinbaseCommerce.' Set Authentication to 'Private key in header.' Key name: 'X-CC-Api-Key', Key value: paste your Coinbase Commerce API key (found in Commerce Dashboard → Settings → API keys). Check the 'Private' checkbox to keep the key server-side. Set the API base URL to https://api.commerce.coinbase.com.

**Expected result:** The CoinbaseCommerce API is configured with secure authentication in the API Connector.

### 2. Create an API call to generate a payment charge

Inside the CoinbaseCommerce API, add a new call named 'create_charge.' Set Use as: Action, Method: POST, URL: https://api.commerce.coinbase.com/charges. Add a header: Content-Type = application/json. In the Body, define the JSON payload with dynamic parameters for name, description, amount, and currency. Initialize the call with test values to map the response fields, especially 'hosted_url' which is the checkout page URL.

```
{
  "name": "<name>",
  "description": "<description>",
  "pricing_type": "fixed_price",
  "local_price": {
    "amount": "<amount>",
    "currency": "<currency>"
  },
  "redirect_url": "<redirect_url>",
  "cancel_url": "<cancel_url>"
}
```

**Expected result:** The create_charge API call is configured and initialized, returning a hosted_url in the response.

### 3. Build the payment workflow on your checkout page

On your checkout page, add a 'Pay with Crypto' button. In the Workflow tab, create: When Button Pay with Crypto is clicked → Action: Plugins → CoinbaseCommerce - create_charge. Set parameters: name = your product name, description = order details, amount = the order total, currency = 'USD', redirect_url = your success page URL, cancel_url = your cancel page URL. Next action: Open an external website → URL = Result of step 1's hosted_url. Also create an 'Order' in your database with status = 'pending' and the charge code from the API response.

**Expected result:** Clicking 'Pay with Crypto' creates a charge and redirects the user to Coinbase Commerce's hosted checkout page.

### 4. Set up a webhook endpoint to receive payment confirmations

Go to the Workflow tab → click the pages dropdown → Backend workflows. Create a new backend workflow called 'coinbase_webhook.' Add a parameter 'event_type' (text). In the workflow, add a condition: Only when event_type is 'charge:confirmed.' The action: Do a search for Orders where charge_code = the charge code from the webhook payload → Make changes: status = 'confirmed.' In your Coinbase Commerce dashboard, go to Settings → Webhook subscriptions → Add endpoint: https://yourapp.bubbleapps.io/api/1.1/wf/coinbase_webhook.

> Pro tip: Always verify webhook signatures to prevent spoofed payment confirmations. Store the webhook shared secret from Coinbase and validate the X-CC-Webhook-Signature header.

**Expected result:** When a customer completes a crypto payment, Coinbase sends a webhook to your Bubble app, which updates the order status to confirmed.

### 5. Display payment status to the user

On your success/redirect page, display the order status. Set the page Type of content to 'Order' and pass the order via URL parameter or data-to-send. Show a Text element: 'When Current Page Order's status is pending → Payment processing... Crypto payments can take 10-30 minutes to confirm.' Add another conditional: 'When status is confirmed → Payment confirmed! Thank you for your order.' Use a 'Do when condition is true' event to auto-refresh the order data every 30 seconds until the status changes.

**Expected result:** Users see real-time payment status that updates from 'pending' to 'confirmed' once the blockchain transaction is verified.

## Complete code example

File: `API Connector payload`

```json
{
  "api_name": "CoinbaseCommerce",
  "authentication": {
    "type": "Private key in header",
    "key_name": "X-CC-Api-Key",
    "key_value": "[YOUR_COINBASE_COMMERCE_API_KEY]"
  },
  "calls": [
    {
      "name": "create_charge",
      "use_as": "Action",
      "method": "POST",
      "url": "https://api.commerce.coinbase.com/charges",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": {
        "name": "[product_name]",
        "description": "[order_description]",
        "pricing_type": "fixed_price",
        "local_price": {
          "amount": "[amount]",
          "currency": "USD"
        },
        "redirect_url": "https://yourapp.com/payment-success",
        "cancel_url": "https://yourapp.com/payment-cancel",
        "metadata": {
          "order_id": "[bubble_order_id]"
        }
      }
    }
  ],
  "webhook_endpoint": {
    "url": "https://yourapp.bubbleapps.io/api/1.1/wf/coinbase_webhook",
    "events": ["charge:confirmed", "charge:failed", "charge:pending"]
  },
  "data_model": {
    "Order": {
      "fields": {
        "user": "User",
        "amount": "number",
        "currency": "text",
        "charge_code": "text",
        "status": "text (pending/confirmed/failed)",
        "payment_method": "text (crypto)"
      }
    }
  }
}
```

## Common mistakes

- **Not enabling the Workflow API before creating backend webhook endpoints** — Backend workflows are not accessible unless the Workflow API is enabled in Settings → API. Your webhook URL will return a 404 error. Fix: Go to Settings → API tab → check 'Enable Workflow API and backend workflows' before setting up the webhook.
- **Expecting instant payment confirmation** — Cryptocurrency transactions require blockchain confirmations which take 10-60 minutes depending on the network. Users may close the page before confirmation arrives. Fix: Show a clear 'payment pending' message and use webhooks to update order status asynchronously. Send an email confirmation when the webhook fires.
- **Not storing the charge code from the API response** — Without the charge code, you cannot match the webhook notification to the correct order in your database. Fix: In the payment workflow, save Result of step 1's code to the Order's charge_code field before redirecting the user.

## Best practices

- Always mark API keys as Private in the API Connector to keep them server-side
- Store the charge code in your Order record to match webhooks to orders
- Handle all webhook event types: charge:confirmed, charge:failed, and charge:pending
- Show users clear messaging about crypto payment processing times (10-60 minutes)
- Send email confirmations when payment is confirmed via the webhook
- Verify webhook signatures to prevent fraudulent payment confirmations
- Log all webhook events for debugging and audit purposes

## Frequently asked questions

### Which cryptocurrencies can I accept with Coinbase Commerce?

Coinbase Commerce supports Bitcoin (BTC), Ethereum (ETH), Litecoin (LTC), Bitcoin Cash (BCH), USD Coin (USDC), and DAI. The list expands over time — check their documentation for the latest supported currencies.

### Do I need to understand blockchain technology to use this?

No. Coinbase Commerce handles all the blockchain complexity. You just create charges via API and receive webhook notifications. You never interact with the blockchain directly.

### How long do crypto payments take to confirm?

Bitcoin typically takes 10-60 minutes for confirmation. Ethereum takes 1-5 minutes. Stablecoins like USDC can confirm in under a minute. Coinbase Commerce sends the webhook only after sufficient confirmations.

### What fees does Coinbase Commerce charge?

Coinbase Commerce charges 1% per transaction. There are no monthly fees or setup costs. This is significantly lower than credit card processing fees (typically 2.9% + 30 cents).

### Can I offer both crypto and credit card payments?

Yes. Add both options on your checkout page. Use the Stripe plugin for credit cards and the Coinbase Commerce API for crypto. Let users choose their preferred payment method.

### Can RapidDev help integrate crypto payments into my Bubble app?

Yes. RapidDev helps founders integrate payment gateways including cryptocurrency processors, with proper webhook handling, order management, and security best practices.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/integrate-a-cryptocurrency-payment-gateway-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/integrate-a-cryptocurrency-payment-gateway-in-bubble