Astro Minimal Boilerplate - Dodo Payments Documentation

Übersicht

Das Astro Minimal Boilerplate bietet einen sofort einsatzbereiten Ausgangspunkt für die Integration von Dodo Payments in Ihre Astro-Anwendung. Diese Vorlage umfasst Checkout-Sitzungen, Webhook-Verarbeitung, Kundenportal und moderne UI-Komponenten, um Ihnen zu helfen, schnell Zahlungen zu akzeptieren.

Dieser Boilerplate verwendet Astro 5 mit TypeScript, Tailwind CSS 4 und den @dodopayments/astro Adapter.

Funktionen

Schnellstart – In weniger als 5 Minuten loslegen
Zahlungsintegration – Vorgefertigter Checkout-Flow mit @dodopayments/astro
Moderne UI – Saubere, dunkel gehaltene Preisseite mit Tailwind CSS
Webhook-Handler – Bereit einsatzfähiger Webhook-Endpunkt für Zahlungsevents
Kundenportal – Abonnementverwaltung mit einem Klick
TypeScript – Vollständig typisiert mit minimalen, fokussierten Typen
Vorbefüllter Checkout – Zeigt, wie Kundendaten übergeben werden, um die Nutzererfahrung zu verbessern

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

Node.js LTS-Version (erforderlich für Astro 5)
Dodo Payments-Konto (um API- und Webhook-Keys vom Dashboard abzurufen)

Schnellstart

Clone the Repository

git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Registriere dich bei Dodo Payments und hole dir deine Zugangsdaten vom Dashboard:

API-Schlüssel: Dashboard → Entwickler → API-Schlüssel
Webhook-Schlüssel: Dashboard → Entwickler → Webhooks

Stelle sicher, dass du dich während der Entwicklung im Testmodus befindest!

Configure Environment Variables

Erstelle eine Datei .env im Stammverzeichnis:

cp .env.example .env

Aktualisieren Sie die Werte mit Ihren Dodo Payments-Anmeldeinformationen:

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode

Committe niemals deine Datei .env in die Versionskontrolle. Sie ist bereits in .gitignore enthalten.

Add Your Products

Aktualisiere src/lib/products.ts mit deinen tatsächlichen Produkt-IDs von Dodo Payments:

export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];

Run the Development Server

npm run dev

Öffne http://localhost:4321, um deine Preisseite zu sehen!

Projektstruktur

src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind

Anpassung

Produktinformationen aktualisieren

Bearbeite src/lib/products.ts, um folgende Elemente anzupassen:

Produkt-IDs (aus deinem Dodo-Dashboard)
Preise
Funktionen
Beschreibungen

Kundendaten vorab ausfüllen

Ersetze in src/components/ProductCard.astro die fest codierten Werte durch deine tatsächlichen Benutzerdaten:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Kundenportal aktualisieren

Ersetze in src/components/Header.astro die fest codierte Kunden-ID durch die tatsächliche Kunden-ID aus deinem Auth-System oder deiner Datenbank:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Sie können einen Testkauf abschließen, um die Kunden-ID für Tests zu erhalten.

Webhook-Ereignisse

Die Boilerplate zeigt, wie man Webhook-Events in src/pages/api/webhook.ts verarbeitet:

onSubscriptionActive – Wird ausgelöst, wenn ein Abonnement aktiv wird
onSubscriptionCancelled – Wird ausgelöst, wenn ein Abonnement gekündigt wird

Fügen Sie Ihre Geschäftslogik in diese Handler ein:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

Fügen Sie bei Bedarf weitere Webhook-Ereignisse hinzu. Für die lokale Entwicklung können Sie Tools wie ngrok verwenden, um einen sicheren Tunnel zu Ihrem lokalen Server zu erstellen und ihn als Ihre Webhook-URL zu verwenden.

Bereitstellung

Dieses Boilerplate verwendet statische Ausgaben mit bedarfsorientierter Rendering für API-Routen. Sie müssen einen Adapter für Ihre Bereitstellungsplattform installieren:

Plattform	Anleitung
Vercel	Bereitstellung auf Vercel
Netlify	Bereitstellung auf Netlify
Cloudflare	Bereitstellung auf Cloudflare

Siehe Astros Bereitstellungsanleitungen für alle Plattformen.

Webhook-URL aktualisieren

Nach der Bereitstellung aktualisieren Sie Ihre Webhook-URL im Dodo Payments Dashboard:

https://your-domain.com/api/webhook

Denk auch daran, die Umgebungsvariable DODO_PAYMENTS_WEBHOOK_KEY in deiner Produktionsumgebung zu aktualisieren, damit sie mit dem Webhook-Signatur-Schlüssel deiner bereitgestellten Domain übereinstimmt.

Fehlersuche

Module not found or build errors

Lösche node_modules und installiere die Abhängigkeiten neu:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Häufige Ursachen:

Ungültige Produkt-ID – überprüfe, ob sie in deinem Dodo-Dashboard existiert
Falscher API-Schlüssel oder Umgebungseinstellung in .env
Prüfe die Browser-Konsole und das Terminal auf Fehler

Webhooks not receiving events

Für lokale Tests verwende ngrok, um deinen Server freizugeben:

ngrok http 4321

Aktualisiere die Webhook-URL in deinem Dodo-Dashboard auf die ngrok-URL. Denk daran, deine .env-Datei mit dem korrekten Webhook-Verifizierungsschlüssel zu aktualisieren.

Customer portal link doesn't work

Ersetze die fest codierte CUSTOMER_ID in src/components/Header.astro durch eine tatsächliche Kunden-ID aus deinem Dodo-Dashboard.Oder integriere dein Authentifizierungssystem und deine Datenbank, um die Kunden-ID dynamisch abzurufen.

Build fails with adapter error

Diese Boilerplate verwendet statische Ausgaben mit bedarfsorientierten API-Routen. Du musst einen Adapter für die Bereitstellung installieren:Siehe Astro’s Deployment-Guides für Details.

Erfahren Sie mehr

Unterstützung

Brauchen Sie Hilfe mit dem Boilerplate?

Treten Sie unserer Discord-Community für Fragen und Diskussionen bei
Überprüfen Sie das GitHub-Repository auf Probleme und Updates
Kontaktieren Sie unser Support-Team für Unterstützung

​Übersicht

​Funktionen

​Voraussetzungen

​Schnellstart

​Projektstruktur

​Anpassung

​Produktinformationen aktualisieren

​Kundendaten vorab ausfüllen

​Kundenportal aktualisieren

​Webhook-Ereignisse

​Bereitstellung

​Webhook-URL aktualisieren

​Fehlersuche

​Erfahren Sie mehr

​Unterstützung

Übersicht

Funktionen

Voraussetzungen

Schnellstart

Projektstruktur

Anpassung

Produktinformationen aktualisieren

Kundendaten vorab ausfüllen

Kundenportal aktualisieren

Webhook-Ereignisse

Bereitstellung

Webhook-URL aktualisieren

Fehlersuche

Erfahren Sie mehr

Unterstützung