Go Boilerplate

GitHub Repository

Minimaler Go- + Dodo Payments-Boilerplate

Übersicht

Das Go-Boilerplate ist ein minimaler Go-Server, der Ihre Dodo Payments-Produkte über eine Preisseite verkauft. Er erstellt Checkout-Sitzungen, verifiziert und verarbeitet Webhooks und öffnet das Customer Portal. Klonen Sie es als Ausgangspunkt für Ihr eigenes Go-Backend.

Das Boilerplate benötigt Go 1.24.4 oder höher, die in seiner go.mod festgelegte Version. Es verwendet ein cmd-, internal- und templates-Layout, rendert die Preisseite mit Go-HTML-Templates und ruft die Dodo Payments API über das dodopayments-go SDK auf.

Funktionen

Schnelle Einrichtung: Klonen Sie das Repository, fügen Sie Ihre API-Schlüssel zu .env hinzu und starten Sie den Server mit make run.
Zahlungsintegration: Ein Checkout-Ablauf, der Checkout-Sitzungen mit dem dodopayments-go SDK erstellt.
Moderne Benutzeroberfläche: Eine Preisseite mit dunklem Design, erstellt mit Go-HTML-Templates und Tailwind CSS.
Webhook-Verarbeitung: Verifiziert die Signatur jedes Webhooks, bevor das Ereignis verarbeitet wird.
Customer Portal: Selbstständige Verwaltung von Abonnements über das Customer Portal.
Go-Best Practices: Eine übersichtliche Projektstruktur mit cmd, internal und templates.
Vorbefüllter Checkout: Übermittelt den Namen und die E-Mail-Adresse des Kunden an den Checkout, damit der Kunde diese nicht erneut eingeben muss.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie:

Go 1.24.4 oder höher. Überprüfen Sie Ihre Version mit go version.
Ein Dodo Payments-Konto, um einen API-Schlüssel und einen Webhook-Signaturschlüssel im Dashboard zu erstellen.
Mindestens ein Produkt, das im Dashboard unter Products erstellt wurde.

Schnellstart

Clone the Repository

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

Install Dependencies

make install

make install führt go mod download und anschließend go mod tidy aus. Um die Module ohne make herunterzuladen, führen Sie Folgendes aus:

go mod download

Get API Credentials

Registrieren Sie sich bei Dodo Payments und kopieren Sie anschließend beide Schlüssel aus dem Dashboard:

API Key: Developer → API Keys
Webhook Key: Developer → Webhooks. Jeder Webhook-Endpunkt verfügt über einen eigenen Signaturschlüssel. Informationen zum Erstellen eines Endpunkts, der Ihren lokalen Server erreicht, finden Sie unter Webhooks lokal testen.

Erstellen Sie beide Schlüssel während der Entwicklung im Testmodus. Um in den Testmodus zu wechseln, deaktivieren Sie den Schalter Live Mode in der Seitenleiste des Dashboards.

Configure Environment Variables

Erstellen Sie im Projektstammverzeichnis aus der Vorlage eine Datei .env:

cp .env.example .env

Legen Sie diese Werte in .env fest:

.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

Der Server liest diese Variablen beim Start ein:

Variable	Erforderlich	Standardwert	Zweck
`DODO_PAYMENTS_API_KEY`	Ja	None	Authentifiziert Anfragen an die Dodo Payments API.
`DODO_PAYMENTS_WEBHOOK_KEY`	Ja	None	Verifiziert die Signatur eingehender Webhooks.
`DODO_PAYMENTS_RETURN_URL`	Nein	`http://localhost:8080`	Die URL, zu der Checkout den Kunden nach der Zahlung weiterleitet.
`DODO_PAYMENTS_ENVIRONMENT`	Nein	`test_mode`	`test_mode` oder `live_mode`.
`PORT`	Nein	`8000`	Der Port, auf dem der Server lauscht.

Der Server wird beim Start beendet, wenn einer der erforderlichen Schlüssel fehlt. .env.example setzt PORT und DODO_PAYMENTS_RETURN_URL auf Port 8080. Diese Seite verwendet Port 8000. Setzen Sie daher beide wie gezeigt auf 8000 oder ersetzen Sie 8000 in den Befehlen auf dieser Seite durch 8080.

Committen Sie Ihre Datei .env niemals in die Versionsverwaltung. Die .gitignore des Repositorys schließt sie bereits aus.

Add Your Products

Ersetzen Sie das Beispielprodukt in internal/lib/products.go durch Ihre Produkte. Kopieren Sie die ID jedes Produkts aus Products im Dashboard:

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 legt nur den auf der Preisseite angezeigten Preis in der kleinsten Währungseinheit fest: 9999 wird als $99.99 angezeigt. Checkout berechnet den Preis des Produkts in Dodo Payments.

Run the Development Server

make run

make run erstellt den Server in bin/server und startet ihn. Um den Server auszuführen, ohne zuvor eine Binärdatei zu erstellen, führen Sie Folgendes aus:

go run cmd/server/main.go

Öffnen Sie http://localhost:8000, um Ihre Preisseite anzuzeigen.

Sie sehen eine Preisseite mit dunklem Design, auf der Ihre kaufbereiten Produkte aufgeführt sind.

Projektstruktur

Das Repository hat folgende Struktur:

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

API-Endpunkte

Das Boilerplate enthält die folgenden vorkonfigurierten Endpunkte:

Endpunkt	Methode	Beschreibung
`/`	GET	Preisseite, die die Produkte in `internal/lib/products.go` auflistet.
`/api/checkout`	POST	Erstellt eine Checkout-Sitzung. Sendet `product_id` sowie optional `quantity` (Standard: `1`) und `customer` (`email`, `name`, `phone`). Gibt `session_id` und `checkout_url` zurück.
`/api/webhook`	POST	Verifiziert und verarbeitet Dodo Payments-Webhooks. Gibt `401` zurück, wenn die Signaturprüfung fehlschlägt.
`/api/customer-portal`	POST	Gibt einen Customer Portal-Link in `portal_url` zurück. Sendet `customer_id` oder `email` mit einem optionalen `name`. Bei alleiniger Angabe einer E-Mail-Adresse sucht der Handler den Kunden und erstellt ihn, falls er nicht vorhanden ist.
`/health`	GET	Zustandsprüfung. Gibt `OK` zurück.

Anpassung

Produktinformationen aktualisieren

Bearbeiten Sie internal/lib/products.go, um Folgendes zu ändern:

Produkt-IDs (aus Products in Ihrem Dodo Payments-Dashboard)
Namen
Auf der Preisseite angezeigte Preise
Funktionen
Beschreibungen

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",
        },
    },
}

Das Template der Preisseite fügt jedem Preis das Suffix /mo hinzu und zeigt Custom anstelle eines Preises an, wenn Price 100000 oder höher ist. Um dies zu ändern, bearbeiten Sie templates/index.html.

Kundendaten vorab ausfüllen

In templates/index.html sendet die Funktion handleCheckout fest codierte Kundendaten an /api/checkout. Ersetzen Sie diese durch die Daten des angemeldeten Benutzers:

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
};

Die Funktion handlePortal verwendet diese Kundendaten erneut und greift auf denselben Beispielnamen und dieselbe Beispiel-E-Mail-Adresse zurück. In einer Produktionsanwendung müssen Sie diese Werte in beiden Funktionen aus Ihrem Authentifizierungssystem übergeben.

Webhook-Ereignisse

internal/api/webhook.go verifiziert jede Anfrage mit client.Webhooks.Unwrap und dem Schlüssel in DODO_PAYMENTS_WEBHOOK_KEY und leitet das Ereignis anhand seines type weiter. Für diese Ereignisse gibt es jeweils einen Handler, und jeder Handler protokolliert die Ereignisdaten:

Ereignis	Beschreibung
`payment.succeeded`	Wird ausgelöst, wenn eine Zahlung erfolgreich ist
`payment.failed`	Wird ausgelöst, wenn ein Zahlungsversuch fehlschlägt
`subscription.active`	Wird ausgelöst, wenn ein Abonnement aktiv wird
`subscription.renewed`	Wird ausgelöst, wenn ein Abonnement für den nächsten Abrechnungszeitraum verlängert wird
`subscription.updated`	Wird ausgelöst, wenn sich ein beliebiges Feld des Abonnements ändert
`subscription.cancelled`	Wird ausgelöst, wenn ein Abonnement gekündigt wird

Der Handler akzeptiert außerdem subscription.on_hold, subscription.failed, subscription.expired und subscription.plan_changed ohne Aktion und protokolliert jeden anderen Ereignistyp als nicht verarbeitet. Er antwortet auf jedes verifizierte Ereignis mit 200. Eine Übersicht über alle Ereignistypen finden Sie im Webhook Event Guide. Fügen Sie den Handler-Funktionen Ihre Geschäftslogik hinzu, um:

Benutzerberechtigungen in Ihrer Datenbank zu aktualisieren
Bestätigungs-E-Mails zu senden
Zugriff auf digitale Produkte bereitzustellen
Analysen und Metriken zu erfassen

Webhooks lokal testen

Dodo Payments kann localhost nicht erreichen. Um während der Entwicklung Webhooks zu empfangen, machen Sie Ihren lokalen Server mit einem Tunnel wie ngrok öffentlich erreichbar:

ngrok http 8000

Fügen Sie im Dodo Payments Dashboard einen Endpunkt mit der von ngrok ausgegebenen Weiterleitungs-URL hinzu, gefolgt von /api/webhook:

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

Kopieren Sie den Signaturschlüssel des Endpunkts in DODO_PAYMENTS_WEBHOOK_KEY und starten Sie den Server anschließend neu.

Bereitstellung

Für die Produktion erstellen

make build kompiliert den Server in bin/server:

make build

Um die Binärdatei ohne make zu erstellen und zu starten, führen Sie Folgendes aus:

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

Auf Vercel bereitstellen

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Fügen Sie nach der Bereitstellung die Variablen aus Ihrer Datei .env den Vercel-Projekteinstellungen hinzu, da .env nicht im Repository enthalten ist. Legen Sie anschließend den Webhook-Endpunkt im Dashboard auf https://yourdomain.com/api/webhook fest.

Docker

Erstellen Sie im Projektstammverzeichnis eine Datei Dockerfile. Die Build-Stage muss Go 1.24.4 oder höher verwenden, passend zu 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"]

Das finale Image kopiert templates/ neben die Binärdatei, da der Server die Templates aus dem Arbeitsverzeichnis lädt. Erstellen und starten Sie das Image:

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

Der Container lauscht auf dem Wert PORT aus .env. Belassen Sie daher PORT=8000 unverändert, damit es zur Portzuordnung passt.

Überlegungen für die Produktion

Bevor Sie die Anwendung in der Produktion bereitstellen:

Setzen Sie DODO_PAYMENTS_ENVIRONMENT auf live_mode.
Verwenden Sie einen Live-Mode-API-Schlüssel aus dem Dashboard.
Verweisen Sie mit dem Webhook-Endpunkt auf Ihre Produktionsdomain und verwenden Sie den Signaturschlüssel dieses Endpunkts.
Setzen Sie DODO_PAYMENTS_RETURN_URL auf eine Seite Ihrer Produktionsdomain.
Stellen Sie jeden Endpunkt über HTTPS bereit.

Fehlerbehebung

Build errors or missing dependencies

Überprüfen Sie, ob go version Go 1.24.4 oder höher meldet, und laden Sie anschließend die Module erneut herunter:

go mod tidy
go mod download

Checkout session creation fails

Häufige Ursachen:

Die Produkt-ID ist ungültig. Überprüfen Sie, ob sie unter Products im selben Modus wie Ihr API-Schlüssel vorhanden ist.
Der API-Schlüssel oder DODO_PAYMENTS_ENVIRONMENT in .env ist falsch. Ein Schlüssel im Testmodus benötigt test_mode.
Die genaue Fehlermeldung finden Sie in den Serverprotokollen. Der Handler protokolliert jede fehlgeschlagene Anfrage, bevor er 500 zurückgibt.

Webhooks not receiving events

Für lokale Tests machen Sie Ihren Server mit ngrok öffentlich erreichbar:

ngrok http 8000

Setzen Sie die Webhook-URL in Ihrem Dodo Payments-Dashboard auf die ngrok-URL. Setzen Sie anschließend DODO_PAYMENTS_WEBHOOK_KEY in .env auf den Signaturschlüssel dieses Endpunkts. Wenn der Server webhook verification failed protokolliert, stimmt der Schlüssel nicht mit dem Endpunkt überein.

Templates not loading

Der Server lädt templates/base.html und templates/index.html aus dem Arbeitsverzeichnis. Starten Sie den Server aus dem Projektstammverzeichnis oder ändern Sie die Template-Pfade in cmd/server/main.go.

Weitere Informationen

Go SDK

Vollständige Go SDK-Dokumentation

Webhooks Documentation

Erfahren Sie mehr über alle Webhook-Ereignisse und Best Practices

Checkout Sessions

Erhalten Sie einen detaillierten Einblick in die Konfiguration von Checkout-Sitzungen

API Reference

Vollständige Dodo Payments API-Dokumentation

Support

Wenn Sie Hilfe zum Boilerplate benötigen:

Stellen Sie Fragen in der Discord-Community.
Sehen Sie im GitHub-Repository nach Problemen und Aktualisierungen.
Kontaktieren Sie das Support-Team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Übersicht

Funktionen

Voraussetzungen

Schnellstart

Projektstruktur

API-Endpunkte

Anpassung

Produktinformationen aktualisieren

Kundendaten vorab ausfüllen

Webhook-Ereignisse

Webhooks lokal testen

Bereitstellung

Für die Produktion erstellen

Auf Vercel bereitstellen

Docker

Überlegungen für die Produktion

Fehlerbehebung

Weitere Informationen

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Support

GitHub Repository

​Übersicht

​Funktionen

​Voraussetzungen

​Schnellstart

​Projektstruktur

​API-Endpunkte

​Anpassung

​Produktinformationen aktualisieren

​Kundendaten vorab ausfüllen

​Webhook-Ereignisse

​Webhooks lokal testen

​Bereitstellung

​Für die Produktion erstellen

​Auf Vercel bereitstellen

​Docker

​Überlegungen für die Produktion

​Fehlerbehebung

​Weitere Informationen

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Support

Übersicht

Funktionen

Voraussetzungen

Schnellstart

Projektstruktur

API-Endpunkte

Anpassung

Produktinformationen aktualisieren

Kundendaten vorab ausfüllen

Webhook-Ereignisse

Webhooks lokal testen

Bereitstellung

Für die Produktion erstellen

Auf Vercel bereitstellen

Docker

Überlegungen für die Produktion

Fehlerbehebung

Weitere Informationen

Support