DOCSEARCHbyAlgolia
Submit Docs

Stripe Firebase Extensions

repository·next·Indexed 19 days ago

https://github.com/invertase/stripe-firebase-extensions

A repository of Firebase extensions built by Stripe to integrate payment capabilities with Firebase and Firestore. It includes the firestore-stripe-payments extension for managing one-time and recurring payments, subscription syncing, and access control via Firebase Authentication, as well as the firestore-stripe-invoices extension for automating the creation and sending of brandable customer invoices.

Tokens
45.2K
Snippets
210
Records
275
Agent score
67%

What's inside stripe-firebase-extensions

  1. Overview of Stripe Firebase Extensions

    next

    This repository provides the source code for Firebase Extensions that enable payment functionality. The extensions are designed to work with Stripe to handle payments, subscriptions, and invoicing within a Firebase environment.

    Available extensions in this repository:

    1. Stripe backend for web, mobile, and subscription payments: Handles the core payment logic and backend integration.
    2. Send invoices using Stripe: Enables the ability to send invoices via Stripe.

  2. Run Payments with Stripe using Firebase Extensions

    next

    The Stripe Firebase Extension controls access to paid content by syncing one-time and recurring payments with Firebase Authentication. It acts as a backend for Stripe payments, supporting several use cases:

    • Stripe Checkout (Web): Process one-time payments or create subscriptions. The extension syncs subscription status to Cloud Firestore and adds custom claims to Firebase Authentication for easy access control.
    • Mobile Payment Sheet: Process payments and set up payment methods on Android, iOS, or React Native using the mobile payment sheet.

    Important Note for Mobile Developers: If you are selling digital products or services (e.g., subscriptions, in-game currency, premium content) within a native mobile app, you must use the app store's in-app purchase APIs (Apple/Google) instead of Stripe to comply with platform guidelines. For all other scenarios, you can use the Stripe SDKs for Android, iOS, React Native, or Flutter.

  3. Send Invoices using Stripe

    next

    The firestore-stripe-invoices extension automates the creation and sending of brandable customer invoices via Stripe. It works by listening to a specified Cloud Firestore collection. When you add a new document to that collection, the extension uses the document's data to create an invoice in Stripe and sends it to the specified email address.

    Invoice Document Schema

    To trigger an invoice, your Firestore document must include an email and an items array. Each item in the array requires an amount, currency, and can optionally include quantity and description.

    Optional Status Syncing

    You can optionally have the extension automatically update the invoice's status in your Firestore document. To enable this, you must register a Stripe webhook that listens for Stripe invoice events.

    Important: During initial installation, leave the Stripe webhook secret parameter empty. You should only provide the actual signing secret after you have registered the webhook in your Stripe dashboard.

    {
  email: "customer@example.com",
  items: [{
    amount: 2000,
    currency: "usd",
    quantity: 2, // Optional, defaults to 1.
    description: "Growth plan"
  }]
}

  4. Use cases for Stripe Firebase Extensions

    next

    The extension serves as a backend for Stripe payments and supports several integration patterns:

    • Web-based One-time Payments: Process one-time payments using Stripe Checkout.
    • Subscriptions & Access Control: Create user subscriptions and manage access control via Firebase Authentication. The extension syncs subscription status to Cloud Firestore and adds custom claims to Firebase Authentication for easy permission management.
    • Mobile Payments: Process payments and manage payment methods using the mobile payment sheet on Android, iOS, or React Native (using the respective Stripe SDKs).

    Important Platform Note: If you are building a native mobile app and selling digital products or services (e.g., subscriptions, in-game currency, premium content), you must use the platform's official in-app purchase APIs (Apple App Store or Google Play Store) instead of Stripe to comply with store guidelines.

  5. Use the @invertase/firestore-stripe-payments Web SDK

    next
    The @invertase/firestore-stripe-payments package is a Web SDK designed to facilitate Stripe payments using Firestore. It provides the client-side logic necessary to interact with the Stripe Firebase Extensions (specifically firestore-stripe-payments and firestore-stripe-invoices) to manage subscriptions, checkouts, and payment statuses directly from your web application.

  7. Assign Custom Claim Roles to Products

    next

    To grant users specific access based on their subscription, set a firebaseRole metadata value on the Stripe product in the Stripe Dashboard. This value is automatically synced as a stripeRole custom claim on the user's Firebase Auth token.

    Client-side validation: When checking roles on the client, you must force-refresh the user token to ensure the claim is present.

    import { getAuth } from 'firebase/auth';

async function getCustomClaimRole() {
  const auth = getAuth();
  await auth.currentUser?.getIdToken(true);
  const decodedToken = await auth.currentUser?.getIdTokenResult();
  return decodedToken?.claims.stripeRole;
}

  8. How the Stripe-Firebase synchronization works

    next

    The extension uses Stripe webhooks and Cloud Functions to maintain synchronization between Stripe and Cloud Firestore:

    • Webhook Processing: When a customer completes a checkout or changes a subscription, Stripe sends a webhook event to a Cloud Function. The extension processes this event to update the corresponding subscription status in Firestore.
    • Custom Claims: If you set a firebaseRole in your product metadata within the Stripe Dashboard, the extension automatically sets the corresponding stripeRole as a custom claim on the user's Firebase Auth token. This allows you to control access to restricted content using Firebase Security Rules.
    • Automatic Cleanup: If a subscription is canceled or a payment fails, the extension updates Firestore and removes the associated custom claim roles, ensuring access control remains accurate.

  10. Instantiate StripePayments using getStripePayments()

    next

    The StripePayments class holds the configuration and state for the SDK. You should not call the constructor directly. Instead, use the getStripePayments() function to obtain an instance of the class, which is required as an argument for almost all other APIs in the library.

    // Do not use: new StripePayments()
// Instead, use the helper function:
const stripePayments = await getStripePayments();

  11. Set up Firebase and Stripe for the extension

    next

    Before installing the extension, you must configure your Firebase and Stripe environments:

    1. Firebase Setup

    • Cloud Firestore: Create a database to store customer and subscription details.
    • Firebase Authentication: Enable the sign-in methods you want to offer your users.
    • Blaze Plan: Your Firebase project must be on the Blaze (pay-as-go) plan.

    2. Stripe Setup

    • Create a restricted API key in the Stripe Dashboard. The key requires:
      • Write access: Customers, Checkout Sessions, and Customer portal.
      • Read-only access: Subscriptions and Prices.

  12. Setup the ESM Vite Example

    next

    To run the ESM example with Vite, follow these steps to configure Firebase and install dependencies:

    1. Prepare the Web SDK: Ensure the web SDK is packed or install a published version >= v0.0.8.
    2. Configure Firebase: Copy the example configuration file and populate it with your project credentials:
      cp src/firebase-config.example.js src/firebase-config.js
    3. Enable Authentication: In the Firebase Console, navigate to Authentication > Sign-in method and enable the Email/Password provider.
    4. Install and Run:
      npm install
npm run dev
    5. Access the App: Open http://localhost:3001 in your browser.
    cp src/firebase-config.example.js src/firebase-config.js
npm install
npm run dev