Go Boilerplate

GitHub Repository

Minimal Go + Dodo Payments boilerplate

Overview

Le boilerplate Go est un serveur Go minimal qui vend vos produits Dodo Payments depuis une page de tarification. Il crée des sessions de paiement, vérifie et traite les webhooks, et ouvre le Customer Portal. Clonez-le comme point de départ pour votre propre backend Go.

Le boilerplate nécessite Go 1.24.4 ou une version ultérieure, la version définie dans son go.mod. Il utilise une structure cmd, internal et templates, affiche la page de tarification avec les modèles HTML de Go et appelle l’API Dodo Payments via le SDK dodopayments-go.

Features

Configuration rapide : clonez le dépôt, ajoutez vos clés API à .env et démarrez le serveur avec make run.
Intégration des paiements : un flux de paiement qui crée des sessions de paiement avec le SDK dodopayments-go.
Interface moderne : une page de tarification sombre créée avec les modèles HTML de Go et Tailwind CSS.
Gestion des webhooks : vérifie la signature de chaque webhook avant de traiter l’événement.
Customer Portal : gestion autonome des abonnements via le Customer Portal.
Bonnes pratiques Go : une structure de projet claire avec cmd, internal et templates.
Paiement prérempli : transmet le nom et l’adresse e-mail du client au paiement, afin qu’il n’ait pas à les saisir à nouveau.

Prerequisites

Avant de commencer, vous avez besoin des éléments suivants :

Go 1.24.4 ou une version ultérieure. Vérifiez votre version avec go version.
Un compte Dodo Payments, pour créer une clé API et une clé de signature de webhook dans le tableau de bord.
Au moins un produit, créé dans Products dans le tableau de bord.

Quick Start

Clone the Repository

git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate

Install Dependencies

make install

make install exécute go mod download, puis go mod tidy. Pour télécharger les modules sans make, exécutez :

go mod download

Get API Credentials

Inscrivez-vous sur Dodo Payments, puis copiez les deux clés depuis le tableau de bord :

Clé API : Developer → API Keys
Clé de webhook : Developer → Webhooks. Chaque endpoint de webhook possède sa propre clé de signature. Pour créer un endpoint qui atteint votre serveur local, consultez Tester les webhooks en local.

Créez les deux clés en mode test pendant le développement. Pour passer en mode test, désactivez le bouton Live Mode dans la barre latérale du tableau de bord.

Configure Environment Variables

Créez un fichier .env à la racine du projet à partir du modèle :

cp .env.example .env

Définissez ces valeurs dans .env :

.env

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

Le serveur lit ces variables au démarrage :

Variable	Obligatoire	Valeur par défaut	Fonction
`DODO_PAYMENTS_API_KEY`	Oui	Aucune	Authentifie les requêtes vers l’API Dodo Payments.
`DODO_PAYMENTS_WEBHOOK_KEY`	Oui	Aucune	Vérifie la signature des webhooks entrants.
`DODO_PAYMENTS_RETURN_URL`	Non	`http://localhost:8080`	URL vers laquelle le paiement redirige le client après le paiement.
`DODO_PAYMENTS_ENVIRONMENT`	Non	`test_mode`	`test_mode` ou `live_mode`.
`PORT`	Non	`8000`	Port sur lequel le serveur écoute.

Le serveur s’arrête au démarrage si l’une des clés obligatoires est manquante. .env.example définit PORT et DODO_PAYMENTS_RETURN_URL sur le port 8080. Cette page utilise le port 8000 ; définissez donc les deux valeurs sur 8000 comme indiqué, ou remplacez 8000 par 8080 dans les commandes de cette page.

Ne commitez jamais votre fichier .env dans le contrôle de version. Le .gitignore du dépôt l’exclut déjà.

Add Your Products

Remplacez le produit d’exemple dans internal/lib/products.go par vos produits. Copiez l’identifiant de chaque produit depuis Products dans le tableau de bord :

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999, // in cents
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
    // ... add more products
}

Price définit uniquement le prix affiché par la page de tarification, dans la plus petite unité monétaire : 9999 s’affiche comme $99.99. Le paiement facture le prix du produit dans Dodo Payments.

Run the Development Server

make run

make run compile le serveur dans bin/server et le démarre. Pour exécuter le serveur sans compiler d’abord un binaire, exécutez :

go run cmd/server/main.go

Ouvrez http://localhost:8000 pour afficher votre page de tarification.

Vous voyez une page de tarification sombre qui répertorie vos produits, prêts à être achetés.

Structure du projet

Le dépôt possède la structure suivante :

go-boilerplate/
├── cmd/
│   └── server/             # Application entry point (main.go)
├── internal/
│   ├── api/                # API handlers: checkout.go, portal.go, webhook.go
│   ├── core/               # Configuration loading (config.go)
│   └── lib/                # Shared logic: products.go, customers.go
├── templates/              # HTML templates: base.html, index.html
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md

Endpoints d’API

Le boilerplate comprend les endpoints préconfigurés suivants :

Endpoint	Méthode	Description
`/`	GET	Page de tarification qui répertorie les produits dans `internal/lib/products.go`.
`/api/checkout`	POST	Crée une session de paiement. Envoyez `product_id`, ainsi que `quantity` facultatif (par défaut `1`) et `customer` (`email`, `name`, `phone`). Renvoie `session_id` et `checkout_url`.
`/api/webhook`	POST	Vérifie et traite les webhooks Dodo Payments. Renvoie `401` lorsque la vérification de signature échoue.
`/api/customer-portal`	POST	Renvoie un lien Customer Portal dans `portal_url`. Envoyez `customer_id`, ou `email` avec un `name` facultatif. Avec uniquement une adresse e-mail, le gestionnaire recherche le client et en crée un s’il n’existe pas.
`/health`	GET	Vérification de l’état. Renvoie `OK`.

Personnalisation

Mettre à jour les informations produit

Modifiez internal/lib/products.go pour changer :

Les identifiants des produits (depuis Products dans votre tableau de bord Dodo Payments)
Les noms
Les prix affichés sur la page de tarification
Les fonctionnalités
Les descriptions

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}

Le modèle de la page de tarification ajoute le suffixe /mo à chaque prix et affiche Custom au lieu d’un prix lorsque Price vaut 100000 ou davantage. Pour modifier ce comportement, éditez templates/index.html.

Préremplir les données client

Dans .env, la fonction handleCheckout envoie des données client codées en dur à /api/checkout. Remplacez-les par les données de l’utilisateur connecté :

const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};

La fonction handlePortal réutilise ces données client et utilise les mêmes nom et adresse e-mail d’exemple comme solution de repli. Dans une application de production, injectez ces valeurs depuis votre système d’authentification dans les deux fonctions.

Événements webhook

internal/api/webhook.go vérifie chaque requête avec client.Webhooks.Unwrap et la clé dans DODO_PAYMENTS_WEBHOOK_KEY, puis achemine l’événement selon son type. Ces événements disposent d’un gestionnaire, et chaque gestionnaire journalise les données de l’événement :

Événement	Description
`payment.succeeded`	Déclenché lorsqu’un paiement réussit
`payment.failed`	Déclenché lorsqu’une tentative de paiement échoue
`subscription.active`	Déclenché lorsqu’un abonnement devient actif
`subscription.renewed`	Déclenché lorsqu’un abonnement est renouvelé pour la période de facturation suivante
`subscription.updated`	Déclenché lorsqu’un champ d’abonnement est modifié
`subscription.cancelled`	Déclenché lorsqu’un abonnement est annulé

Le gestionnaire accepte également subscription.on_hold, subscription.failed, subscription.expired et subscription.plan_changed sans effectuer d’action, et journalise tout autre type d’événement comme non géré. Il répond avec 200 à chaque événement vérifié. Pour connaître tous les types d’événements, consultez le Guide des événements webhook. Ajoutez votre logique métier aux fonctions de gestion pour :

Mettre à jour les autorisations des utilisateurs dans votre base de données
Envoyer des e-mails de confirmation
Provisionner l’accès aux produits numériques
Suivre les analyses et les métriques

Tester les webhooks en local

Dodo Payments ne peut pas atteindre localhost. Pour recevoir des webhooks pendant le développement, exposez votre serveur local avec un tunnel tel que ngrok :

ngrok http 8000

Dans le tableau de bord Dodo Payments, ajoutez un endpoint avec l’URL de transfert affichée par ngrok, suivie de /api/webhook :

https://your-ngrok-url.ngrok.io/api/webhook

Copiez la clé de signature de l’endpoint dans DODO_PAYMENTS_WEBHOOK_KEY, puis redémarrez le serveur.

Déploiement

Compiler pour la production

make build compile le serveur dans bin/server :

make build

Pour compiler et démarrer le binaire sans make, exécutez :

go build -o bin/server cmd/server/main.go
./bin/server

Déployer sur Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Après le déploiement, ajoutez les variables de votre fichier .env aux paramètres du projet Vercel, car .env ne se trouve pas dans le dépôt. Définissez ensuite votre endpoint webhook dans le tableau de bord sur https://yourdomain.com/api/webhook.

Docker

Créez un fichier Dockerfile à la racine du projet. L’étape de compilation doit utiliser Go 1.24.4 ou une version ultérieure pour correspondre à go.mod :

FROM golang:1.24-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]

L’image finale copie templates/ à côté du binaire, car le serveur charge les modèles depuis le répertoire de travail. Compilez et exécutez l’image :

docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo

Le conteneur écoute sur la valeur PORT de .env ; conservez donc PORT=8000 pour qu’elle corresponde au mappage des ports.

Considérations pour la production

Avant de déployer en production :

Définissez DODO_PAYMENTS_ENVIRONMENT sur live_mode.
Utilisez une clé API en mode réel depuis le tableau de bord.
Dirigez l’endpoint webhook vers votre domaine de production et utilisez la clé de signature de cet endpoint.
Définissez DODO_PAYMENTS_RETURN_URL sur une page de votre domaine de production.
Servez chaque endpoint via HTTPS.

Résolution des problèmes

Build errors or missing dependencies

Vérifiez que go version indique Go 1.24.4 ou une version ultérieure, puis téléchargez à nouveau les modules :

go mod tidy
go mod download

Checkout session creation fails

Causes courantes :

L’identifiant du produit est invalide. Vérifiez qu’il existe dans Products, dans le même mode que votre clé API.
La clé API ou DODO_PAYMENTS_ENVIRONMENT dans .env est incorrecte. Une clé en mode test nécessite test_mode.
Pour connaître l’erreur exacte, consultez les journaux du serveur. Le gestionnaire journalise chaque requête échouée avant de renvoyer 500.

Webhooks not receiving events

Pour les tests locaux, exposez votre serveur avec ngrok :

ngrok http 8000

Définissez l’URL du webhook dans votre tableau de bord Dodo Payments sur l’URL ngrok. Définissez ensuite DODO_PAYMENTS_WEBHOOK_KEY dans .env sur la clé de signature de cet endpoint. Si les journaux du serveur indiquent webhook verification failed, la clé ne correspond pas à l’endpoint.

Templates not loading

Le serveur charge templates/base.html et templates/index.html depuis le répertoire de travail. Démarrez le serveur depuis la racine du projet ou modifiez les chemins des modèles dans cmd/server/main.go.

En savoir plus

Go SDK

Documentation complète du SDK Go

Webhooks Documentation

Découvrez tous les événements webhook et les bonnes pratiques

Checkout Sessions

Découvrez en détail la configuration des sessions de paiement

API Reference

Documentation complète de l’API Dodo Payments

Assistance

Pour obtenir de l’aide concernant le boilerplate :

Posez vos questions dans la communauté Discord.
Consultez le dépôt GitHub pour connaître les problèmes et les mises à jour.
Contactez l’équipe d’assistance.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Overview

Features

Prerequisites

Quick Start

Structure du projet

Endpoints d’API

Personnalisation

Mettre à jour les informations produit

Préremplir les données client

Événements webhook

Tester les webhooks en local

Déploiement

Compiler pour la production

Déployer sur Vercel

Docker

Considérations pour la production

Résolution des problèmes

En savoir plus

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Assistance

GitHub Repository

​Overview

​Features

​Prerequisites

​Quick Start

​Structure du projet

​Endpoints d’API

​Personnalisation

​Mettre à jour les informations produit

​Préremplir les données client

​Événements webhook

​Tester les webhooks en local

​Déploiement

​Compiler pour la production

​Déployer sur Vercel

​Docker

​Considérations pour la production

​Résolution des problèmes

​En savoir plus

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Assistance

Overview

Features

Prerequisites

Quick Start

Structure du projet

Endpoints d’API

Personnalisation

Mettre à jour les informations produit

Préremplir les données client

Événements webhook

Tester les webhooks en local

Déploiement

Compiler pour la production

Déployer sur Vercel

Docker

Considérations pour la production

Résolution des problèmes

En savoir plus

Assistance