Payments

Dirstarter uses Stripe for payment processing and subscription management. This integration handles expedited listings, featured spots, and recurring subscriptions.

Stripe Setup

Create a Stripe account at stripe.com
Get your API keys from the dashboard
Add the following environment variables:

.env

STRIPE_SECRET_KEY=sk_test_...

We only use the secret key. No need to create a publishable key.

Product Configuration

We recommend creating the following products in your Stripe dashboard:

Free

{
  name: "Free Listing",
  description: "Free listing with wait time",
  amount: 0,
  currency: "usd",
  type: "one_time",
  features: [
    "• {queue} processing time", // will be replaced with the actual wait time
    "✗ No content updates",
    "✗ Do-follow link to your website",
    "✗ No featured spot",
    "✗ No prominent placement",
  ]
}

Expedited (One-time payment)

{
  name: "Expedited Listing",
  description: "Skip the queue and get published within 24 hours",
  amount: 97, // set your own price
  currency: "usd",
  type: "one_time",
  features: [
    "✓ 24h processing time",
    "✓ Unlimited content updates",
    "✗ Do-follow link to your website",
    "✗ No featured spot",
    "✗ No prominent placement",
  ]
}

Featured (Subscription)

{
  name: "Featured Listing",
  description: "Featured listing with homepage spot",
  amount: 197, // set your own price
  currency: "usd",
  type: "recurring",
  interval: "month",
  features: [
    "✓ 12h processing time",
    "✓ Unlimited content updates",
    "✓ Do-follow link to your website",
    "✓ Featured spot on homepage",
    "✓ Prominent placement"
  ]
}

The icons at the beginning of each feature are optional, but recommended for better readability. They are rendered using proper colors and icons.

You can quickly set up the recommended Stripe products and prices using the provided script in your project at scripts/setup-stripe-products.ts. This script will create all necessary products and prices in your Stripe account as defined for Dirstarter.

To run the script, use:

bun run scripts/setup-stripe-products.ts

If you are not using Bun, you can install the ts-node package to run the script.

Make sure your environment variables are set up with your Stripe secret key before running the script. This is useful for initial setup or replicating your Stripe environment.

Webhook Setup

Stripe webhooks are used to handle asynchronous events like successful payments and subscription changes.

Local Development

In local development, you can use the Stripe CLI to forward events to your local server.

Install Stripe CLI

Terminal

brew install stripe/stripe-cli/stripe

stripe login

Forward Events

stripe listen --forward-to localhost:3000/api/stripe/webhooks

The webhook secret is printed in the terminal. Copy it and add it to your environment variables.

.env

STRIPE_WEBHOOK_SECRET=whsec_...

Trigger Test Events

stripe trigger checkout.session.completed
stripe trigger customer.subscription.created

Production

Go to Stripe Webhooks Dashboard

Add endpoint: https://your-domain.com/api/stripe/webhooks

Select events to listen for:

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted

Copy the webhook secret and add it to your environment variables.

.env

STRIPE_WEBHOOK_SECRET=whsec_...

Webhook Events

The boilerplate handles these webhook events:

Expedited Listings

app/api/stripe/webhooks/route.ts

case "checkout.session.completed":
  if (event.data.object.metadata?.tool) {
    // Send out expedited email notification to the admin
  }
  if (event.data.object.metadata?.ads) {
    // Schedule ad listing
  }
  break

Featured Listings

case "customer.subscription.created":
  // Activate featured listing
  break

case "customer.subscription.deleted":
  // Deactivate featured listing
  break

Documentation

Stripe Setup

Product Configuration

Populating Stripe Products

Webhook Setup

Local Development

Production

Webhook Events

On this page

Build your directory, launch, earn