Maruthi-portfolio stripe

Introduction

Replit offers a native integration with Stripe that allows users to implement payments in their applications

Prerequisites

1. These packages must be installed in the workspace root package.json:

   • stripe

     - Official Stripe SDK for API operations

   • stripe-replit-sync

     - Handles webhook processing and database sync. Documentation: https://www.npmjs.com/package/stripe-replit-sync

   If they are not installed, use npm to install them:

   $ cd /home/runner/workspace && npm install <packages>

2. The Stripe integration must be connected to the repl. You can do this by proposing the integration. Reference the

   integrations

   skill if necessary. Once connected, create

   stripeClient.ts

   using the template from the code-templates reference -- this file fetches Stripe credentials from the Replit connection API and provides the authenticated client via

   getUncachableStripeClient()

   .

   Create it in the

   server/

   directory.

3. Ensure a PostgreSQL database exists. If you don't have one yet, use the tool to create a PostgreSQL database. Never use memory database for storing Stripe data.

You are required to ensure these requirements are met before setting up or using Stripe.

Project Structure

• Scripts directory:

  scripts/

  at the workspace root (e.g.,

  scripts/seed-products.ts

  )
• Run a script:

  npx tsx scripts/<script>.ts

• API server directory:

  server/

• Client app directory:

  client/

Reference files use these terms. Map them to these concrete paths.

Initial Setup: Step-by-Step Implementation

Ensure prerequisites are met. Do not proceed until you have done so.

Follow these steps in order when implementing Stripe integration for the user. Create a task list to track implementation progress.

Read the code-templates reference file for full code file templates to use during these steps.

1. Set Up Database

   Create the users table with Stripe ID references:

   CREATE TABLE users (
     id TEXT PRIMARY KEY,
     email TEXT,
     stripe_customer_id TEXT,
     stripe_subscription_id TEXT,
     created_at TIMESTAMP DEFAULT NOW()
   );
   

   Important: stripe-replit-sync creates the

   stripe

   schema automatically. Create application tables (users, orders, etc.) in the public schema, not in the stripe schema.

2. Create Webhook Handler

   In the API server create

   webhookHandlers.ts

   - use the template provided in the code-templates reference. It handles webhook processing by calling

   getStripeSync()

   from stripeClient.

3. Initialize Stripe on Startup

   Add this initialization function to the API server's index.ts. Important order:

   1. Run migrations to create schema
   2. Get StripeSync instance
   3. Set up managed webhook (uses StripeSync)
   4. Sync existing data with syncBackfill()

   import { runMigrations } from 'stripe-replit-sync';
   import { getStripeSync } from './stripeClient';
   
   async function initStripe() {
     const databaseUrl = process.env.DATABASE_URL;
     if (!databaseUrl) throw new Error('DATABASE_URL required');
   
     // 1. Create stripe schema and tables
     await runMigrations({ databaseUrl });
   
     // 2. Get StripeSync instance (needed for webhook setup and backfill)
     const stripeSync = await getStripeSync();
   
     // 3. Set up managed webhook
     const webhookBaseUrl = `https://${process.env.REPLIT_DOMAINS?.split(',')[0]}`;
     const { webhook } = await stripeSync.findOrCreateManagedWebhook(
       `${webhookBaseUrl}/api/stripe/webhook`
     );
   
     // 4. Sync all existing Stripe data
     await stripeSync.syncBackfill();
   }
   
   await initStripe();
   

4. Register Webhook Route in index.ts

   Critical: Register the webhook route BEFORE

   express.json()

   middleware. See the indexTemplate for the correct pattern:
   1. Route path is

      /api/stripe/webhook

   2. Webhook route uses

      express.raw()

      to get Buffer in

      req.body

   3. Webhook route is registered BEFORE

      app.use(express.json())

   4. Other routes registered after get parsed JSON automatically

   app.post(
     '/api/stripe/webhook',
     express.raw({ type: 'application/json' }),
     async (req, res) => {
       const signature = req.headers['stripe-signature'];
       if (!signature) return res.status(400).json({ error: 'Missing signature' });
   
       const sig = Array.isArray(signature) ? signature[0] : signature;
   
       await WebhookHandlers.processWebhook(req.body as Buffer, sig);
       res.status(200).json({ received: true });
     }
   );
   
   app.use(express.json()); // Now apply to other routes
   

5. Create Storage Layer

   Create

   storage.ts

   - use the template provided in the code-templates reference. Query Stripe data from PostgreSQL

   stripe

   schema using standard SQL queries.

6. Set Up Other Routes

   Create

   routes.ts

   - use the template provided in the code-templates reference for products, prices, checkout, etc. These routes are registered AFTER

   express.json()

   so they get parsed JSON.

7. Create Products Script (Recommended)

   Create

   seed-products.ts

   - a script to add products and prices to Stripe via the API. This is the recommended way to create products. Run it manually when creating products.

   Use the seed-products template from the code-templates reference as a starting point:

   • Modify the script to create the specific products needed
   • Run it manually when adding products:

     node seed-products.js

   • Webhooks automatically sync created products to the database
   • Stripe handles test vs live mode based on API keys

   import { getUncachableStripeClient } from './stripeClient';
   
   async function createProducts() {
     const stripe = await getUncachableStripeClient();
   
     // Create product
     const product = await stripe.products.create({
       name: 'Pro Plan',
       description: 'Professional subscription',
     });
   
     // Create prices for the product
     const monthlyPrice = await stripe.prices.create({
       product: product.id,
       unit_amount: 2900, // $29.00
       currency: 'usd',
       recurring: { interval: 'month' },
     });
   
     console.log('Created:', product.id, monthlyPrice.id);
   }
   
   createProducts();
   

   Usage: Run this script in development when you need to create or add products.

   Optional idempotency: To make the script safe to run multiple times, check if specific products exist first:

   const products = await stripe.products.search({ query: "name:'Pro Plan'" });
   if (products.data.length > 0) {
     console.log('Pro Plan already exists');
     return;
   }
   

Database Architecture

1. stripe-replit-sync creates and manages the

   stripe

   schema automatically - DO NOT create any tables in the stripe schema
2. The stripe schema contains tables for: products, prices, customers, subscriptions, payment_intents, etc.
3. Application tables are created in the public schema (or other schemas) - e.g., users, orders, etc.
4. Application tables store Stripe IDs as TEXT columns (e.g.,

   stripe_customer_id TEXT

   ,

   stripe_subscription_id TEXT

   )
5. Replit automatically handles deployment and Stripe data migration moving from sandbox to live.

Synchronization Flow

1. Stripe credentials are fetched from Replit connection API

2. runMigrations()

   creates the stripe schema and all Stripe tables (idempotent, safe to run on every startup)

3. syncBackfill()

   syncs ALL existing Stripe data from Stripe API to the local PostgreSQL database on startup
4. Managed webhooks are automatically configured by

   stripe-replit-sync

5. Webhooks keep data up-to-date when changes occur in Stripe after startup
6. Application queries Stripe data from PostgreSQL

   stripe

   schema (fast, no API calls needed)

Storing Data

Do NOT Create Product Tables or Maintain Any Other Source of Truth for Stripe Data

Bad -- creates duplicate product storage:

export const products = pgTable("products", {
  id: varchar("id").primaryKey(),
  name: text("name"),
  price: integer("price"),
  // ... custom fields
});

Correct Approach:

• NO product tables needed!
• Query directly from

  stripe.products

  and

  stripe.prices

• Use Stripe's metadata field for ALL custom attributes

Creating Products and Prices

NEVER insert data directly into the stripe schema tables. Instead:

• Create products via Stripe API (using scripts)
• Stripe webhooks managed by stripe-replit-sync automatically sync the data to the stripe schema in the local database
• Query the synced data from the

  stripe

  schema tables using standard SQL queries

Create products in Stripe with metadata (use API or script):

await stripe.products.create({
  name: "Product Name",
  description: "...",
  images: ["https://..."],
  metadata: {
    category: "electronics",
    customField1: "value1",
    featured: "true",
  }
});
await stripe.prices.create({
  product: product.id,
  unit_amount: 9999,
  currency: 'usd',
});

Query from synced stripe tables:

const result = await db.execute(sql`
  SELECT
    p.id,
    p.name,
    p.metadata,
    pr.id as price_id,
    pr.unit_amount
  FROM stripe.products p
  JOIN stripe.prices pr ON pr.product = p.id
  WHERE p.active = true
`);

Use real Stripe price IDs in checkout:

// CORRECT
{ price: "price_1ABC...", quantity: 1 }
// WRONG - Never use price_data
{
  price_data: {
    unit_amount: 9999,
    currency: 'usd',
    product_data: { name: "..." }
  }
}

Decision Tree: When to Create Tables

• Products/Prices? -- NO, use

  stripe.products

  /

  stripe.prices

• Customers? -- NO, use

  stripe.customers

• Subscriptions? -- NO, use

  stripe.subscriptions

• Orders/Cart/User preferences? -- YES, these aren't in Stripe
• Relationships to Stripe data? -- YES, store Stripe IDs as foreign keys

Key Principle: "If it exists in Stripe, it belongs in Stripe"

• Don't duplicate Stripe data in your own tables
• Don't create parallel storage systems
• Stripe + metadata = your complete product catalog
• Your tables should only store data that Stripe doesn't manage

Creating products: Write a seed script that calls Stripe API (

stripe.products.create()

,

stripe.prices.create()

). Run this script in development to create your products. Webhooks automatically sync them to the database. Replit handles deployment automatically.

Workflow:

# Development:
# - Run seed script to create products in Stripe (test mode)
# - syncBackfill() syncs them to local database

# Deployment (handled by Replit):
# - Replit copies products/prices from dev Stripe to prod Stripe
# - Your code runs unchanged, syncBackfill() syncs prod database

# Production:
# - Modify products via Stripe Dashboard (scripts can't run in deployments)
# - Webhooks automatically sync changes to database

Publishing with Stripe

To publish the app with working Stripe payments:

1. Go to the Stripe Dashboard (https://dashboard.stripe.com/apikeys)
2. Get live API keys (starts with

   pk_live_

   and

   sk_live_

   )
3. Open the Publish pane in the Workspace
4. Enter the live Publishable Key and Secret Key
5. Publish the app

Placeholder Keys (User-Requested Only):

Only offer placeholder keys if the user explicitly asks to publish without live Stripe keys and understands the consequences. Do NOT use these for any other purpose.

If the user confirms they want to proceed without live keys, suggest the following values to them:

• Publishable Key:

  pk_live_abcdef

• Secret Key:

  sk_live_abcdef

Consequences the user must understand:

• Placeholder keys will NOT process real payments
• The product catalog and checkout will not function on the published URL
• Real Stripe keys must be added later for payments to work

Deleting Stripe Integration

To remove the Stripe integration from the project:

1. In the project, open the "Integrations" tab
2. Go to "Stripe" and click "Manage"
3. Select "Edit" then "Delete"

Key Rules

DO:

• Create products via Stripe API using scripts (never with SQL INSERT)
• Query Stripe data from PostgreSQL

  stripe

  schema tables (products, prices, customers, subscriptions, etc.)
• Store Stripe IDs in application tables as TEXT (e.g.,

  stripe_customer_id TEXT

  )
• Keep webhook handler minimal (just call

  processWebhook

  with payload and signature)
• Let

  syncBackfill()

  sync existing Stripe data on startup
• Let managed webhooks handle webhook configuration automatically
• Register webhook route BEFORE

  express.json()

  middleware

ABSOLUTELY DO NOT:

• Create any tables in the

  stripe

  schema - stripe-replit-sync manages this automatically
• Insert, update, or delete data in

  stripe

  schema tables - only query from them
• Use SQL INSERT for products, prices, customers, subscriptions - use Stripe API instead
• Manually copy database data between environments - Replit handles Stripe product/price copying during deployment
• Add custom logic in webhook handler beyond calling

  processWebhook

• Skip running

  runMigrations()

  or

  syncBackfill()

• Create StripeSync instance before calling

  runMigrations()

Common Mistakes

Database - DO NOT create Stripe tables:

-- WRONG - Creating Stripe tables manually
CREATE TABLE products (
  id TEXT PRIMARY KEY,
  name TEXT,
  price INTEGER
);

-- CORRECT - Create application tables, store Stripe IDs
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  stripe_customer_id TEXT
);
-- stripe-replit-sync creates stripe.products, stripe.prices, etc. automatically

Data Creation - Use Stripe API Scripts, NOT SQL:

-- WRONG - Inserting Stripe data with SQL
INSERT INTO stripe.products (id, name, description)
VALUES ('prod_123', 'Pro Plan', 'Professional subscription');

// CORRECT - Use Stripe API in a script
const stripe = await getUncachableStripeClient();
const product = await stripe.products.create({
  name: 'Pro Plan',
  description: 'Professional subscription',
});
// Webhook syncs this to stripe.products automatically

Initialization Order:

// WRONG - Creating StripeSync before migrations
const stripeSync = await getStripeSync();
await runMigrations({ databaseUrl });

// CORRECT - Migrations first, then StripeSync
await runMigrations({ databaseUrl });
const stripeSync = await getStripeSync();
await stripeSync.findOrCreateManagedWebhook(...);
await stripeSync.syncBackfill();

Frontend - Must parse JSON responses:

// WRONG - returns Response object
const response = await apiRequest('POST', '/api/checkout', { priceId });
return response;

// CORRECT - parse to get data
const response = await apiRequest('POST', '/api/checkout', { priceId });
return await response.json();

Backend - Webhook route ordering:

// WRONG - Webhook after express.json()
app.use(express.json());
app.post('/api/stripe/webhook', ...);  // Too late! Body already parsed

// CORRECT - Webhook BEFORE express.json()
app.post('/api/stripe/webhook', express.raw({ type: 'application/json' }),
  async (req, res) => {
    await WebhookHandlers.processWebhook(req.body, sig);
  }
);
app.use(express.json());  // Now apply to other routes

References

• ./references/code-templates.md -- Code file templates for initial Stripe setup. ONLY read this reference when performing initial setup of Stripe in a project that does not already have it configured. Do not read for subsequent modifications, queries, or other Stripe operations.