Astro Minimal Boilerplate - Dodo Payments Documentation

Aperçu

Le boilerplate minimal Astro fournit un point de départ prêt à l’emploi pour intégrer Dodo Payments avec votre application Astro. Ce modèle inclut des sessions de paiement, la gestion des webhooks, un portail client et des composants UI modernes pour vous aider à commencer à accepter des paiements rapidement.

Ce modèle utilise Astro 5 avec TypeScript, Tailwind CSS 4 et l’adaptateur @dodopayments/astro.

Caractéristiques

Configuration rapide - Démarrez en moins de 5 minutes
Intégration de paiement - Flux de paiement préconfiguré utilisant @dodopayments/astro
Interface moderne - Page tarifaire épurée à thème sombre avec Tailwind CSS
Gestionnaire de webhook - Point de terminaison webhook prêt à l’emploi pour les événements de paiement
Portail client - Gestion des abonnements en un clic
TypeScript - Entièrement typé avec des types minimaux et ciblés
Paiement pré-rempli - Montre comment transmettre les données client pour améliorer l’expérience utilisateur

Prérequis

Avant de commencer, assurez-vous d’avoir :

Version LTS de Node.js (nécessaire pour Astro 5)
Compte Dodo Payments (pour accéder aux clés API et Webhook depuis le tableau de bord)

Démarrage Rapide

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

Inscrivez-vous sur Dodo Payments et récupérez vos identifiants depuis le tableau de bord :

Clé API : Tableau de bord → Développeur → Clés API
Clé Webhook : Tableau de bord → Développeur → Webhooks

Assurez-vous d’être en mode Test pendant le développement !

Configure Environment Variables

Créez un fichier .env dans le répertoire racine :

cp .env.example .env

Mettez à jour les valeurs avec vos identifiants Dodo Payments :

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

Ne commettez jamais votre fichier .env dans le contrôle de version. Il est déjà inclus dans .gitignore.

Add Your Products

Mettez à jour src/lib/products.ts avec vos identifiants de produit réels de 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

Ouvrez http://localhost:4321 pour voir votre page tarifaire !

Structure du Projet

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

Personnalisation

Mettre à Jour les Informations sur les Produits

Modifiez src/lib/products.ts pour changer :

Identifiants de produit (depuis votre tableau de bord Dodo)
Tarifs
Fonctionnalités
Descriptions

Pré-remplir les Données Client

Dans src/components/ProductCard.astro, remplacez les valeurs codées en dur par vos données utilisateur réelles :

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

Mettre à Jour le Portail Client

Dans src/components/Header.astro, remplacez l’ID client codé en dur par l’ID client réel provenant de votre système d’authentification ou de votre base de données :

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

Vous pouvez effectuer un achat test pour obtenir l’identifiant client pour les tests.

Événements Webhook

Le modèle montre la gestion des événements webhook dans src/pages/api/webhook.ts :

onSubscriptionActive - Déclenché lorsqu’un abonnement devient actif
onSubscriptionCancelled - Déclenché lorsqu’un abonnement est annulé

Ajoutez votre logique métier à l’intérieur de ces gestionnaires :

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

Ajoutez d’autres événements webhook si nécessaire. Pour le développement local, vous pouvez utiliser des outils comme ngrok pour créer un tunnel sécurisé vers votre serveur local et l’utiliser comme votre URL de webhook.

Déploiement

Ce boilerplate utilise une sortie statique avec un rendu à la demande pour les routes API. Vous devrez installer un adaptateur pour votre plateforme de déploiement :

Plateforme	Guide
Vercel	Déployer sur Vercel
Netlify	Déployer sur Netlify
Cloudflare	Déployer sur Cloudflare

Consultez les guides de déploiement d’Astro pour toutes les plateformes.

Mettre à Jour l’URL du Webhook

Après le déploiement, mettez à jour votre URL de webhook dans le Tableau de bord Dodo Payments :

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

N’oubliez pas non plus de mettre à jour la variable d’environnement DODO_PAYMENTS_WEBHOOK_KEY dans votre environnement de production pour qu’elle corresponde à la clé de signature webhook de votre domaine déployé.

Dépannage

Module not found or build errors

Supprimez node_modules et réinstallez les dépendances :

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Causes courantes :

ID du produit invalide - vérifiez qu’il existe dans votre tableau de bord Dodo
Mauvaise clé API ou mauvais paramètre d’environnement dans .env
Vérifiez la console du navigateur et le terminal pour les erreurs

Webhooks not receiving events

Pour les tests locaux, utilisez ngrok pour exposer votre serveur :

ngrok http 4321

Mettez à jour l’URL du webhook dans votre tableau de bord Dodo avec l’URL ngrok. Pensez à mettre à jour votre fichier .env avec la clé de vérification webhook appropriée.

Customer portal link doesn't work

Remplacez l’CUSTOMER_ID codée en dur dans src/components/Header.astro par un ID client réel provenant de votre tableau de bord Dodo.Ou intégrez votre système d’authentification et votre base de données pour récupérer dynamiquement l’ID client.

Build fails with adapter error

Ce modèle utilise une sortie statique avec des routes API à la demande. Vous devez installer un adaptateur pour le déploiement :Consultez les guides de déploiement d’Astro pour plus de détails.

En Savoir Plus

Support

Besoin d’aide avec le boilerplate ?

Rejoignez notre communauté Discord pour des questions et des discussions
Consultez le référentiel GitHub pour les problèmes et les mises à jour
Contactez notre équipe de support pour assistance

​Aperçu

​Caractéristiques

​Prérequis

​Démarrage Rapide

​Structure du Projet

​Personnalisation

​Mettre à Jour les Informations sur les Produits

​Pré-remplir les Données Client

​Mettre à Jour le Portail Client

​Événements Webhook

​Déploiement

​Mettre à Jour l’URL du Webhook

​Dépannage

​En Savoir Plus

​Support

Aperçu

Caractéristiques

Prérequis

Démarrage Rapide

Structure du Projet

Personnalisation

Mettre à Jour les Informations sur les Produits

Pré-remplir les Données Client

Mettre à Jour le Portail Client

Événements Webhook

Déploiement

Mettre à Jour l’URL du Webhook

Dépannage

En Savoir Plus

Support