Omnibase

Stripe Integration Overview

Learn how OmniBase handles billing, subscriptions, and payment processing with Stripe

Stripe Integration

OmniBase provides a comprehensive "Stripe as Code" approach to billing configuration, enabling version control, rollbacks, audit trails, and enterprise-grade payment processing.

Key Features

The Problem with Native Stripe

Stripe's configuration presents several challenges for production systems:

ChallengeDescription
ImmutabilityProducts and prices with payment history cannot be deleted
No Version ControlNo built-in rollback or history tracking
Environment SyncDifficult to sync configurations between dev/staging/prod
Free TiersStripe doesn't natively support $0 prices
Enterprise PricingNo built-in support for custom per-customer pricing

OmniBase Solution

OmniBase stores your Stripe configuration in PostgreSQL and syncs it to Stripe, providing:

  • Version Control — Every configuration change is tracked with full history
  • Rollbacks — Revert to any previous configuration instantly
  • Audit Trails — Complete history of all billing changes with timestamps
  • Free Tiers — Support $0 pricing stored locally (bypasses Stripe's limitation)
  • Config ID Mapping — Human-readable IDs (pro_monthly) mapped to Stripe IDs (price_1ABC...)
  • Enterprise Pricing — Template-based and custom per-tenant pricing

Quick Start

Create Your Configuration

Create a configuration file in your project:

omnibase/stripe/subscriptions.config.json
{
  "$schema": "https://dashboard.omnibase.tech/api/stripe-config.schema.json",
  "version": "1.0.0",
  "products": [
    {
      "id": "starter",
      "name": "Starter Plan",
      "description": "Perfect for individuals",
      "type": "service",
      "prices": [
        {
          "id": "starter_monthly",
          "amount": 0,
          "currency": "usd",
          "interval": "month",
          "public": true,
          "ui": {
            "display_name": "Free",
            "price_display": { "custom_text": "Free" }
          }
        }
      ]
    },
    {
      "id": "pro",
      "name": "Professional",
      "description": "For growing businesses",
      "type": "service",
      "prices": [
        {
          "id": "pro_monthly",
          "amount": 4900,
          "currency": "usd",
          "interval": "month",
          "public": true,
          "default": true
        },
        {
          "id": "pro_yearly",
          "amount": 49000,
          "currency": "usd",
          "interval": "year",
          "public": true
        }
      ],
      "ui": {
        "highlighted": true,
        "badge": "Most Popular"
      }
    }
  ]
}

Push to Stripe

Use the CLI to validate and push your configuration:

# Validate configuration without pushing
omnibase stripe validate

# Push configuration to Stripe
omnibase stripe push

This will:

  1. Validate your configuration against the JSON schema
  2. Create/update products and prices in Stripe
  3. Store the configuration version in PostgreSQL
  4. Generate config ID to Stripe ID mappings

Use in Your Application

Fetch the configuration and create checkouts:

app/(dashboard)/subscriptions/page.tsx
import { V1StripeApi, V1PaymentsApi } from '@omnibase/core-js';

export default async function SubscriptionsPage() {
  const stripeApi = new V1StripeApi(config);
  const paymentsApi = new V1PaymentsApi(config);

  // Get available plans
  const { data: stripeConfig } = await stripeApi.getStripeConfig();

  async function checkout(priceId: string) {
    'use server';
    const { data } = await paymentsApi.createCheckout({
      createCheckoutRequest: {
        priceId,
        successUrl: `${process.env.APP_URL}/subscriptions?success=true`,
        cancelUrl: `${process.env.APP_URL}/subscriptions`,
        trialPeriodDays: 14,
        allowPromotionCodes: true,
      },
    });
    redirect(data.url);
  }

  return <PricingTable products={stripeConfig.products} onSelect={checkout} />;
}
components/Pricing.tsx
import { useEffect, useState } from 'react';
import { V1StripeApi, V1PaymentsApi, Product } from '@omnibase/core-js';

export function Pricing() {
  const [products, setProducts] = useState<Product[]>([]);

  useEffect(() => {
    const stripeApi = new V1StripeApi(config);
    stripeApi.getStripeConfig().then(({ data }) => {
      setProducts(data.products);
    });
  }, []);

  const handleCheckout = async (priceId: string) => {
    const paymentsApi = new V1PaymentsApi(config);
    const { data } = await paymentsApi.createCheckout({
      createCheckoutRequest: {
        priceId,
        successUrl: `${window.location.origin}/success`,
        cancelUrl: window.location.href,
      },
    });
    window.location.href = data.url;
  };

  return <PricingTable products={products} onSelect={handleCheckout} />;
}
server/checkout.ts
import { Configuration, V1StripeApi, V1PaymentsApi } from '@omnibase/core-js';

const config = new Configuration({
  basePath: process.env.OMNIBASE_API_URL,
  headers: { Cookie: cookieHeader },
});

// Get configuration
const stripeApi = new V1StripeApi(config);
const { data: stripeConfig } = await stripeApi.getStripeConfig();

// Create checkout session
const paymentsApi = new V1PaymentsApi(config);
const { data: checkout } = await paymentsApi.createCheckout({
  createCheckoutRequest: {
    priceId: 'pro_monthly',
    successUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/pricing',
  },
});

console.log('Checkout URL:', checkout.url);

Architecture Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Config Files   │────▶│  OmniBase API    │────▶│   Stripe    │
│  (JSON/YAML)    │     │  (PostgreSQL)    │     │   (Live)    │
└─────────────────┘     └──────────────────┘     └─────────────┘
        │                       │                       │
        │                       ▼                       │
        │               ┌──────────────────┐            │
        │               │  ID Mappings     │            │
        │               │  config_id ↔     │◀───────────┘
        │               │  stripe_id       │
        │               └──────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌──────────────────┐
│  Version        │     │  Change          │
│  History        │     │  Detection       │
└─────────────────┘     └──────────────────┘

Key Components:

  1. Configuration Files — JSON files defining products, prices, meters, webhooks, coupons
  2. PostgreSQL Storage — Versioned configuration with full history
  3. ID Mapping — Bi-directional mapping between config IDs and Stripe IDs
  4. Stripe Sync — Intelligent diffing and synchronization to Stripe API

Configuration File Structure

OmniBase supports multiple configuration files for better organization:

webhook.config.json
subscriptions.config.json
usage-billing.config.json
enterprise.config.json

Each file follows the same schema with optional sections:

{
  "$schema": "https://dashboard.omnibase.tech/api/stripe-config.schema.json",
  "version": "1.0.0",
  "webhooks": [],      // Optional: Webhook endpoints
  "meters": [],        // Optional: Billing meters for metered pricing
  "products": [],      // Required: At least one product
  "coupons": [],       // Optional: Discount coupons
  "promotion_codes": [] // Optional: Promotion codes for coupons
}

Supported Currencies

OmniBase supports 20 currencies:

CurrencyCodeCurrencyCode
US DollarusdEuroeur
British PoundgbpCanadian Dollarcad
Australian DollaraudJapanese Yenjpy
Indian RupeeinrBrazilian Realbrl
Mexican PesomxnSingapore Dollarsgd
Hong Kong DollarhkdNew Zealand Dollarnzd
Swiss FrancchfSwedish Kronasek
Danish KronedkkNorwegian Kronenok
Polish ZlotyplnCzech Korunaczk
Israeli ShekelilsSouth African Randzar

CLI Commands

CommandDescription
omnibase stripe pushPush local configuration to Stripe
omnibase stripe pullPull configuration from Stripe account
omnibase stripe validateValidate configuration without pushing
omnibase stripe historyView configuration version history
omnibase stripe webhook secretRetrieve webhook signing secrets

API Endpoints

Public Endpoints (No Auth Required)

EndpointDescription
GET /api/v1/stripe/schemaGet JSON schema for configuration
GET /api/v1/stripe/configGet public configuration (filtered)
GET /api/v1/stripe/config/prices/:idGet price by config ID
GET /api/v1/stripe/config/products/:idGet product by config ID
GET /api/v1/stripe/config/meters/:idGet meter by config ID
POST /api/v1/stripe/config/prices/:id/calculateCalculate cost for quantity

Admin Endpoints (Service Key Required)

EndpointDescription
GET /api/v1/stripe/admin/configGet full configuration (unfiltered)
POST /api/v1/stripe/admin/configUpdate configuration
GET /api/v1/stripe/admin/config/historyGet configuration history
GET /api/v1/stripe/admin/config/pullPull from Stripe
POST /api/v1/stripe/admin/config/validateValidate configuration
POST /api/v1/stripe/admin/config/resetReset/archive all resources
GET /api/v1/stripe/admin/webhooksList webhooks with secrets

What's Next?

On this page