Dodo Payments

Get API key

After you create your Dodo Payments account, go to Developer > API Keys in the dashboard and generate an API key for your app.

TurboStarter uses the server-side Dodo SDK, so you only need the secret API key.

For local development, use Test Mode so you can safely test checkouts and webhooks without affecting live transactions.

Set environment variables

You need to set the following environment variables:

DODO_PAYMENTS_API_KEY="" # Your Dodo Payments API key
DODO_PAYMENTS_WEBHOOK_KEY="" # Your Dodo Payments webhook secret key
DODO_PAYMENTS_ENVIRONMENT="test_mode" # "test_mode" or "live_mode"

Please do not add the secret keys to the .env file in production. During development, you can place them in .env.local as it's not committed to the repository. In production, set them in the environment variables of your hosting provider.

Create products

For your users to choose from the available plans, you need to create those products first in Dodo Payments.

Create one product per purchasable billing variant you want to offer in TurboStarter.

This is important because the current Dodo Payments provider implementation uses the billing variant id as the Dodo product_id during checkout and subscription sync.

Unlike Stripe, Dodo Payments does not map naturally to a single product with multiple prices in the current TurboStarter implementation. Instead, each variant in your billing config should point at the exact Dodo product you want to sell.

Create a webhook

To sync subscription status, successful payments, failed payments, and one-time orders back into your database, you need to set up a webhook.

The webhook handling code comes ready to use with TurboStarter. You only need to create the endpoint in Dodo Payments and point it to your app.

To configure a new webhook, go to Developer > Webhooks in the Dodo Payments dashboard and click Add Webhook.

Select the following events:

• For subscriptions:
  • subscription.active
  • subscription.updated
  • subscription.on_hold
  • subscription.renewed
  • subscription.plan_changed
  • subscription.failed
  • subscription.cancelled
  • subscription.expired
• For one-off payments and checkout completion:
  • payment.succeeded
  • payment.failed
  • payment.cancelled
  • payment.processing

After creating the webhook, copy its Signing Secret and store it in:

DODO_PAYMENTS_WEBHOOK_KEY=<your-webhook-secret>

To get the callback URL for the webhook, you can either use a local development URL or the URL of your deployed app:

Local development

You have two good options for local webhook testing:

dodo login

dodo wh listen --forward-to http://localhost:3000/api/billing/webhook/dodo-payments

dodo wh trigger

ngrok http 3000

Production deployment

When going to production, configure the webhook URL in Dodo Payments using the same endpoint path:

/api/billing/webhook/dodo-payments

If your app is hosted at https://myapp.com, then the webhook URL should be:

https://myapp.com/api/billing/webhook/dodo-payments

All the relevant events above are already handled by TurboStarter. If you want to handle more events, check Webhooks for more information.

Configure the customer portal

TurboStarter uses the Dodo Payments Customer Portal API to create a billing portal session for the current customer and redirect them to Dodo's hosted portal.

That means your users can manage subscriptions, billing history, invoices, and payment methods without you building a custom management UI.

The current implementation creates a dynamic portal session server-side using the Dodo customer id, so there is no extra app-side setup required beyond:

1. making sure the customer exists in Dodo Payments
2. keeping your API key and webhook key configured correctly
3. using the correct Dodo environment (test_mode or live_mode)

If you want to explore the hosted portal outside the app flow, Dodo Payments also provides static environment-specific customer portal links based on your business_id.