Skip to main content

​
Overview

The Astro minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Astro application. This template includes authentication, webhook handling, and basic payment setup to help you start accepting payments quickly.
This boilerplate uses Astro with TypeScript and includes example implementations for checkout sessions and webhook verification.

​
Quick Start

1

Clone the Repository

Clone the boilerplate repository and navigate to the project directory:
git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
2

Get Your API Credentials

Obtain your credentials from the Dodo Payments dashboard in Test Mode:
  • API Key: Navigate to Developer → API Keys in your dashboard
  • Webhook Signing Key: Navigate to Developer → Webhooks in your dashboard
Start with Test Mode to safely test your integration without processing real payments.
3

Configure Environment Variables

Create a .env file in the root directory:
touch .env
Add your Dodo Payments credentials:
.env
DODO_API_KEY_TEST=your_test_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
Never commit your .env file to version control. It’s already included in .gitignore.
4

Configure Webhook Localhost

When testing webhooks locally, expose your localhost using tools like ngrok:
ngrok http 4321
Add the ngrok URL to the allowed_hosts list in astro.config.mjs for webhook delivery:
astro.config.mjs
export default defineConfig({
  server: {
    host: true,
    allowedHosts: ['your-ngrok-url.ngrok.io']
  }
});
This step is required for webhooks to be delivered to your local development environment.
5

Install Dependencies

Install the required npm packages:
npm install
6

Run the Development Server

Start the Astro development server:
npm run dev
Your application will be available at http://localhost:4321.
You’re ready to start building! The boilerplate includes example routes and components to help you understand the integration.

​
What’s Included

The boilerplate comes with pre-configured essentials:

Checkout Integration

Example implementation for creating and handling checkout sessions

Webhook Handler

Secure webhook endpoint with signature verification

TypeScript Support

Full TypeScript configuration with proper type definitions

Tailwind CSS

Pre-configured styling with Tailwind CSS

​
Project Structure

dodo-astro-minimal-boilerplate/
├── src/
│   ├── pages/
│   │   ├── api/
│   │   │   └── webhooks.ts     # Webhook handler
│   │   └── index.astro         # Home page with examples
│   └── lib/
│       └── dodo.ts             # Dodo Payments client setup
├── .env.example                # Environment variables template
├── astro.config.mjs            # Astro configuration
└── package.json

​
Next Steps

Once you have the boilerplate running:
1

Create Your Products

Add products in your Dodo Payments dashboard to enable checkout functionality.
2

Test Webhooks Locally

Use ngrok to expose your local webhook endpoint and update the allowed_hosts in astro.config.mjs:
ngrok http 4321
Add the ngrok URL to your webhook settings in the dashboard.
3

Customize the Integration

Adapt the example code to match your application’s needs and design.
4

Go Live

When ready, switch to Live Mode API keys and deploy your application.

​
Additional Resources

Astro Adapter

Learn about our comprehensive Astro adapter for advanced integrations

Integration Guide

Detailed guide for implementing one-time payments

Webhook Events

Complete reference for all webhook event types

API Reference

Explore the full Dodo Payments API documentation

​
Support

Need help with the boilerplate?