Dodo Payments Provider

Dodo Payments is a modern payment infrastructure built specifically for SaaS applications. It provides flexible billing models including subscription, usage-based, and hybrid pricing.

Setup

1. Create a Dodo Payments Account

1. Sign up at https://dodopayments.com
2. Complete your account setup
3. Navigate to the Dashboard

2. Get Your API Key

1. Go to Settings → API Keys in your dashboard
2. You'll see two modes:
   • Test Mode: For development
   • Live Mode: For production
3. Copy the API key for the mode you're using

Where to find API Key:

• Dashboard → Settings → API Keys
• Test mode keys start with test_
• Live mode keys start with live_

3. Create Products

1. Go to Products in your dashboard
2. Click Create Product
3. Fill in product details:
   • Product name (e.g., "Pro Plan")
   • Description
   • Pricing model (subscription/one-time)
4. Set pricing:
   • For subscriptions: Choose interval (monthly/yearly)
   • Set price amount and currency
5. Copy the Product ID after creation

Example Products:

• Pro Monthly: Recurring, $19/month → Product ID: prod_xxxxx
• Pro Yearly: Recurring, $190/year → Product ID: prod_xxxxx
• Lifetime: One-time, $199 → Product ID: prod_xxxxx

4. Set Up Webhooks

Webhooks notify your application about payment events.

For Production:

1. Go to Settings → Webhooks in your Dodo Payments dashboard
2. Click Add Webhook
3. Enter the webhook endpoint URL: https://yourdomain.com/api/webhooks/dodopayments
4. Select events to listen to based on your payment types:

For One-Time Payments:

• checkout.session.completed (required) - Records the purchase when checkout completes

For Subscriptions:

• subscription.created (required) - Creates subscription record
• subscription.updated (required) - Updates subscription status/plan
• subscription.cancelled (required) - Removes subscription when canceled

If you use both payment types, select all events above.

5. After creating the webhook, copy the Secret Key displayed in the webhook settings
   • This secret is used to verify webhook signatures (HMAC SHA256)
   • Keep this secret secure and never expose it in client-side code

For Local Development:

Use a tunneling service like ngrok:

# Start ngrok
ngrok http 3000

# Use the ngrok URL in webhook settings
https://your-ngrok-url.ngrok.io/api/webhooks/dodopayments

Important: You can create up to 5 webhook endpoints in Dodo Payments.

5. Configure Environment Variables

Add these variables to your .env.local file:

# Dodo Payments API Key
DODO_PAYMENTS_API_KEY=test_xxxxxxxxxxxxx  # Use live_ for production

# Dodo Payments Webhook Secret Key (for signature verification)
DODO_PAYMENTS_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Your Price IDs (use Dodo Payments Product IDs)
NEXT_PUBLIC_PRICE_ID_LIFETIME=prod_xxxxx
NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY=prod_xxxxx
NEXT_PUBLIC_PRICE_ID_PRO_YEARLY=prod_xxxxx
NEXT_PUBLIC_PRICE_ID_ENTERPRISE=prod_xxxxx

Where to find these:

• API Key: Dashboard → Settings → API Keys (separate keys for test and live mode)
• Webhook Secret: Dashboard → Settings → Webhooks → Copy the Secret Key after creating webhook endpoint
• Price IDs: Dashboard → Products → Copy Product ID (use as Price ID)

Security Best Practices:

• Keep your webhook secret secure and never expose it in client-side code
• Rotate the webhook secret periodically for enhanced security
• Dodo Payments uses HMAC SHA256 to sign webhooks with headers: webhook-id, webhook-signature, webhook-timestamp

Configuration

Set Dodo Payments as your payment provider in config/index.ts:

export const config = {
  payments: {
    provider: "dodopayments",
    plans: {
      lifetime: {
        recommended: true,
        prices: [
          {
            type: "one-time",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_LIFETIME as string,
            amount: 199,
            currency: "USD",
          },
        ],
      },
      pro: {
        recommended: false,
        prices: [
          {
            type: "subscription",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY as string,
            amount: 19,
            currency: "USD",
            interval: "month",
          },
          {
            type: "subscription",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_PRO_YEARLY as string,
            amount: 190,
            currency: "USD",
            interval: "year",
          },
        ],
      },
      enterprise: {
        recommended: false,
        prices: [
          {
            type: "subscription",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_ENTERPRISE as string,
            amount: 99,
            currency: "USD",
            interval: "month",
            seats: {
              min: 5,
              max: 100,
            },
          },
        ],
      },
    },
  },
};

Advanced Features

Trial Periods

Offer free trials for subscriptions:

{
  type: "subscription",
  productId: process.env.NEXT_PUBLIC_PRICE_ID_PRO as string,
  amount: 19,
  currency: "USD",
  interval: "month",
  trialPeriodDays: 14, // 14-day free trial
}

When creating a checkout, the trial period is automatically applied.

Seat-Based Billing with Proration

Enable per-seat pricing with automatic prorated charges:

{
  type: "subscription",
  productId: process.env.NEXT_PUBLIC_PRICE_ID_ENTERPRISE as string,
  amount: 99,
  currency: "USD",
  interval: "month",
  seats: {
    min: 5,
    max: 100,
  },
}

Proration Behavior:

• Adding seats: Prorated charge for remaining period
• Removing seats: Prorated credit applied to next invoice
• Proration mode: prorated_immediately (default)

Usage-Based Pricing

Dodo Payments supports usage-based pricing models (see Dodo Payments Documentation for details).