Coinbase API

Go to commerce.coinbase.com and create an account if you don't have one. After logging in, navigate to Settings (gear icon, top right) → API Keys and click 'Create an API Key'. Copy the key immediately — it is shown only once. Then scroll down to the Webhook Subscriptions section and create a new webhook subscription; you will paste the Cloud Function URL here after deployment in step 4. Also note your webhook shared secret from this section — you will need it for HMAC signature verification. Next, decide whether you also want to show live crypto prices or account balances (the Coinbase App API at api.coinbase.com). If yes, go to coinbase.com → Settings → API (under the developer menu) and create a separate API key with read-only permissions — this is a different product with a different key from Commerce. Store both keys securely; you will add them as environment variables in your Cloud Functions, never in FlutterFlow directly. A quick note on the two products: Coinbase Commerce handles merchant payments (charges, webhooks, order management) at api.commerce.coinbase.com. The Coinbase App API at api.coinbase.com handles account data, prices, and portfolio information. They have separate keys, separate base URLs, and separate use cases. Mixing them up is a common mistake that produces confusing authentication errors.

In Firebase Console, navigate to Functions and open the Cloud Functions editor, or use your local Firebase project. Create a new HTTPS function (callable or HTTP trigger — HTTP trigger is simpler here) that accepts the charge details from FlutterFlow and calls the Coinbase Commerce POST /charges endpoint. The function receives the item name, amount in the display currency (e.g. USD), and a redirect URL from FlutterFlow. It then posts to https://api.commerce.coinbase.com/charges with the X-CC-Api-Key header set to your Commerce API key (stored as a Cloud Function environment variable, never hardcoded). The response includes a hosted_url — your function extracts this and returns it to FlutterFlow as a JSON response. Use the Firebase CLI to set your environment variables: firebase functions:config:set coinbase.commerce_api_key='your_key_here'. In the function code, access it via functions.config().coinbase.commerce_api_key (for Firebase Functions v1) or process.env for v2. Deploy the function and copy its HTTPS URL. Be aware that CORS matters for FlutterFlow web builds — add the cors npm package to allow requests from your FlutterFlow app's domain. Native iOS and Android builds don't enforce CORS, but web does. Once deployed, go back to Coinbase Commerce Settings → Webhook Subscriptions and paste the second Cloud Function URL (which you will deploy in step 4) as the webhook endpoint.

1// Firebase Cloud Functions v2 — charge creation (index.js)
2const { onRequest } = require('firebase-functions/v2/https');
3const { defineSecret } = require('firebase-functions/params');
4const cors = require('cors')({ origin: true });
5const fetch = require('node-fetch');
6
7const COINBASE_COMMERCE_KEY = defineSecret('COINBASE_COMMERCE_KEY');
8
9exports.createCoinbaseCharge = onRequest(
10  { secrets: [COINBASE_COMMERCE_KEY] },
11  async (req, res) => {
12    cors(req, res, async () => {
13      if (req.method !== 'POST') {
14        return res.status(405).json({ error: 'Method not allowed' });
15      }
16      const { name, description, amount, currency, orderId } = req.body;
17      try {
18        const response = await fetch(
19          'https://api.commerce.coinbase.com/charges',
20          {
21            method: 'POST',
22            headers: {
23              'Content-Type': 'application/json',
24              'X-CC-Api-Key': COINBASE_COMMERCE_KEY.value(),
25              'X-CC-Version': '2018-03-22',
26            },
27            body: JSON.stringify({
28              name,
29              description,
30              pricing_type: 'fixed_price',
31              local_price: { amount: String(amount), currency },
32              metadata: { order_id: orderId },
33            }),
34          }
35        );
36        const data = await response.json();
37        if (!response.ok) {
38          return res.status(response.status).json({ error: data });
39        }
40        return res.json({
41          charge_id: data.data.id,
42          hosted_url: data.data.hosted_url,
43          expires_at: data.data.expires_at,
44        });
45      } catch (err) {
46        return res.status(500).json({ error: err.message });
47      }
48    });
49  }
50);

In FlutterFlow, click API Calls in the left navigation sidebar, then click + Add → Create API Group. Name it 'CoinbaseCommerce' and set the base URL to your Firebase Cloud Function's base domain (e.g. https://us-central1-yourproject.cloudfunctions.net). This is your Cloud Function's URL, not Coinbase's URL directly. Inside the API Group, click + Add API Call. Name it 'CreateCharge'. Set the method to POST and the endpoint to /createCoinbaseCharge (matching your function name). In the Variables tab, add variables for name (String), description (String), amount (String — always pass crypto amounts as strings to avoid float rounding), currency (String, e.g. 'USD'), and orderId (String). In the Body tab, select JSON and map each variable using the {{ variable }} syntax: { "name": "{{ name }}", "description": "{{ description }}", "amount": "{{ amount }}", "currency": "{{ currency }}", "orderId": "{{ orderId }}" }. Click Test to fire the call with sample values. In the Response & Test tab, paste the sample JSON response from your Cloud Function and click Generate JSON Paths. Map $.hosted_url, $.charge_id, and $.expires_at as extracted response values. For the WebView: go to Custom Code → + Add → Widget. Name it 'CoinbaseWebView'. In the Dependencies field, add the webview_flutter package (flutter.dev pub.dev page). Paste a minimal WebView widget that accepts a 'url' parameter (String). Build the widget, then drop it onto a page — set the url parameter to the hosted_url from the API response. Set width to double.infinity and height to a suitable value (e.g. MediaQuery.of(context).size.height * 0.85) so the hosted checkout fills the screen.

1// Custom Widget — CoinbaseWebView (custom_widget.dart)
2import 'package:flutter/material.dart';
3import 'package:webview_flutter/webview_flutter.dart';
4
5class CoinbaseWebView extends StatefulWidget {
6  const CoinbaseWebView({super.key, required this.url, this.width, this.height});
7
8  final String url;
9  final double? width;
10  final double? height;
11
12  @override
13  State<CoinbaseWebView> createState() => _CoinbaseWebViewState();
14}
15
16class _CoinbaseWebViewState extends State<CoinbaseWebView> {
17  late final WebViewController _controller;
18
19  @override
20  void initState() {
21    super.initState();
22    _controller = WebViewController()
23      ..setJavaScriptMode(JavaScriptMode.unrestricted)
24      ..loadRequest(Uri.parse(widget.url));
25  }
26
27  @override
28  Widget build(BuildContext context) {
29    return SizedBox(
30      width: widget.width ?? double.infinity,
31      height: widget.height ?? MediaQuery.of(context).size.height * 0.85,
32      child: WebViewWidget(controller: _controller),
33    );
34  }
35}

Crypto payment confirmation is asynchronous — the customer's transaction must be confirmed by the blockchain network before Coinbase marks the charge as 'COMPLETED'. You cannot rely on the WebView redirect URL to confirm payment; a user could navigate to a success URL without having paid. The only trustworthy signal is the Coinbase Commerce webhook, which fires a POST request to your Cloud Function URL after network confirmation. Deploy a second HTTPS Cloud Function to handle this webhook. The function must verify the X-CC-Webhook-Signature header by computing HMAC-SHA256 of the raw request body using your webhook shared secret. Use the crypto module (built into Node.js) for this. CRITICAL: you must read the raw body bytes, not a parsed JSON object — parsing JSON first will break the HMAC calculation because byte-level formatting differs. If the signature matches, parse the event type from the body. The key events are: 'charge:confirmed' (payment received and confirmed on-chain — mark order as paid), 'charge:failed' (charge expired without payment), and 'charge:pending' (transaction broadcast but not yet confirmed — update status to 'pending' in Firestore). Extract the metadata.order_id you embedded when creating the charge, and use it to update the corresponding Firestore document. After deploying this function, go to Coinbase Commerce Settings → Webhook Subscriptions and register the function's URL. Coinbase will send a test webhook you can use to verify the signature logic is working before going live. Return HTTP 200 quickly — Coinbase will retry if it receives a non-200 response or no response within a timeout.

1// Firebase Cloud Functions v2 — webhook handler (webhookHandler.js)
2const { onRequest } = require('firebase-functions/v2/https');
3const { defineSecret } = require('firebase-functions/params');
4const { getFirestore } = require('firebase-admin/firestore');
5const { initializeApp } = require('firebase-admin/app');
6const crypto = require('crypto');
7
8initializeApp();
9const db = getFirestore();
10
11const WEBHOOK_SECRET = defineSecret('COINBASE_WEBHOOK_SECRET');
12
13exports.coinbaseWebhook = onRequest(
14  { secrets: [WEBHOOK_SECRET], rawBody: true },
15  async (req, res) => {
16    if (req.method !== 'POST') {
17      return res.status(405).send('Method Not Allowed');
18    }
19    const signature = req.headers['x-cc-webhook-signature'];
20    const rawBody = req.rawBody; // raw Buffer — do NOT use req.body here
21    const expectedSig = crypto
22      .createHmac('sha256', WEBHOOK_SECRET.value())
23      .update(rawBody)
24      .digest('hex');
25
26    if (signature !== expectedSig) {
27      console.error('Webhook signature mismatch');
28      return res.status(401).send('Unauthorized');
29    }
30
31    const event = JSON.parse(rawBody.toString());
32    const { type, data } = event;
33    const orderId = data?.metadata?.order_id;
34
35    if (!orderId) {
36      return res.status(200).send('No order_id in metadata');
37    }
38
39    const orderRef = db.collection('orders').doc(orderId);
40
41    if (type === 'charge:confirmed') {
42      await orderRef.update({ status: 'paid', confirmedAt: new Date() });
43    } else if (type === 'charge:pending') {
44      await orderRef.update({ status: 'pending' });
45    } else if (type === 'charge:failed') {
46      await orderRef.update({ status: 'failed' });
47    }
48
49    return res.status(200).send('OK');
50  }
51);

With the Cloud Function and webhook in place, you can now build the complete user flow in FlutterFlow. Create a page with a 'Pay with Crypto' button. In the Action Flow Editor, wire the button to: (1) call the CreateCharge API Call with the order details from page state, (2) store the returned hosted_url in a Page State variable (String), (3) navigate to the WebView page or open a bottom sheet containing the CoinbaseWebView widget with the url parameter bound to the hosted_url state variable. For the status screen: create a Firestore document listener on the user's order document. In FlutterFlow, use a backend query (Firestore → Collection → Single Document) with real-time updates enabled on the page. Bind the order status field to a conditional widget that shows: 'Awaiting payment' when status is 'created', 'Processing on blockchain' when status is 'pending', 'Payment confirmed!' when status is 'paid', and 'Charge expired' when status is 'failed'. Use a CircularProgressIndicator on the pending state to communicate that confirmation is in progress. Also ensure you pass a unique orderId when creating the charge — this is how the webhook handler finds the right Firestore document. A good pattern is to create the Firestore order document first (with status 'created') and use its document ID as the orderId metadata on the charge. That way the webhook can always look up the order even if the charge_id is unavailable. If you'd prefer to skip building the Cloud Functions and WebView widget yourself, RapidDev's team builds FlutterFlow integrations like this every week — including the full crypto payment flow with webhook verification. Book a free scoping call at rapidevelopers.com/contact.

If you want to show live BTC/ETH/USDC prices in your app (a price ticker, a 'current value' display on an invoice, or a currency converter), you can add a direct FlutterFlow API Call to the Coinbase App API at api.coinbase.com. This is a different product from Commerce and uses a different API key. In FlutterFlow, go to API Calls → + Add → Create API Group. Name it 'CoinbaseAppAPI' and set the base URL to https://api.coinbase.com. Add a shared header: Authorization: Bearer {{ apiKey }}. Then add an API Call named 'GetSpotPrice' with method GET and endpoint /v2/prices/{{ currencyPair }}/spot (e.g. BTC-USD). In the Variables tab, add currencyPair (String). In the Response & Test tab, map $.data.amount as a JSON Path to extract the price. Note: The App API endpoint /v2/prices/{currency_pair}/spot is actually public (no auth required for spot prices) — check Coinbase's current docs, as public endpoints may not require the Bearer header. The 10,000 requests per hour limit applies to authenticated calls. For a simple price ticker refreshed every 30 seconds, you can use the Timer action in FlutterFlow to periodically re-call this API. Remember: keep the App API key in an FF App State variable only if it is a public/read-only key. If your App API key has any write permissions, route it through a Cloud Function just as you did for Commerce charges.

1// FlutterFlow API Call config (reference)
2// API Group: CoinbaseAppAPI
3// Base URL: https://api.coinbase.com
4// Shared Header: Authorization: Bearer {{ apiKey }}
5//
6// API Call: GetSpotPrice
7// Method: GET
8// Endpoint: /v2/prices/{{ currencyPair }}/spot
9// Variables: currencyPair (String, e.g. 'BTC-USD')
10//
11// Sample response:
12// { "data": { "base": "BTC", "currency": "USD", "amount": "67432.51" } }
13//
14// JSON Paths:
15// $.data.amount  → priceAmount (String)
16// $.data.base    → baseCurrency (String)
17// $.data.currency → quoteCurrency (String)