Go Boilerplate

GitHub Repository

Boilerplate minimale Go + Dodo Payments

Panoramica

Il boilerplate Go è un server Go minimale che vende i tuoi prodotti Dodo Payments da una pagina dei prezzi. Crea sessioni di checkout, verifica e gestisce i webhook e apre il Customer Portal. Clonalo come punto di partenza per il tuo backend Go.

Il boilerplate richiede Go 1.24.4 o versioni successive, la versione impostata nel suo go.mod. Utilizza un layout cmd, internal e templates, esegue il rendering della pagina dei prezzi con i template HTML di Go e chiama l’API Dodo Payments tramite l’SDK dodopayments-go.

Caratteristiche

Configurazione rapida: clona il repository, aggiungi le tue chiavi API a .env e avvia il server con make run.
Integrazione dei pagamenti: un flusso di checkout che crea sessioni di checkout con l’SDK dodopayments-go.
UI moderna: una pagina dei prezzi a tema scuro realizzata con i template HTML di Go e Tailwind CSS.
Gestione dei webhook: verifica la firma di ogni webhook prima di elaborare l’evento.
Customer Portal: gestione self-service degli abbonamenti tramite il Customer Portal.
Best practice Go: una struttura del progetto pulita con cmd, internal e templates.
Checkout precompilato: invia il nome e l’email del cliente al checkout, così il cliente non deve inserirli di nuovo.

Requisiti

Prima di iniziare, ti occorrono:

Go 1.24.4 o versioni successive. Controlla la tua versione con go version.
Un account Dodo Payments, per creare una chiave API e una chiave di firma dei webhook nella dashboard.
Almeno un prodotto, creato nella sezione Products della dashboard.

Avvio Rapido

Clone the Repository

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

Install Dependencies

make install

make install esegue go mod download e poi go mod tidy. Per scaricare i moduli senza make, esegui:

go mod download

Get API Credentials

Registrati su Dodo Payments, quindi copia entrambe le chiavi dalla dashboard:

Chiave API: Developer → API Keys
Chiave webhook: Developer → Webhooks. Ogni endpoint webhook ha una propria chiave di firma. Per creare un endpoint che raggiunga il tuo server locale, consulta Testing Webhooks Locally.

Crea entrambe le chiavi in modalità test durante lo sviluppo. Per passare alla modalità test, disattiva l’interruttore Live Mode nella barra laterale della dashboard.

Configure Environment Variables

Crea un file .env nella directory principale del progetto a partire dal template:

cp .env.example .env

Imposta questi valori in .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

Il server legge queste variabili all’avvio:

Variabile	Obbligatoria	Predefinito	Scopo
`DODO_PAYMENTS_API_KEY`	Sì	Nessuno	Autentica le richieste all’API Dodo Payments.
`DODO_PAYMENTS_WEBHOOK_KEY`	Sì	Nessuno	Verifica la firma dei webhook in arrivo.
`DODO_PAYMENTS_RETURN_URL`	No	`http://localhost:8080`	L’URL a cui checkout indirizza il cliente dopo il pagamento.
`DODO_PAYMENTS_ENVIRONMENT`	No	`test_mode`	`test_mode` o `live_mode`.
`PORT`	No	`8000`	La porta su cui il server resta in ascolto.

Il server si arresta all’avvio se manca una delle due chiavi obbligatorie. .env.example imposta PORT e DODO_PAYMENTS_RETURN_URL sulla porta 8080. Questa pagina utilizza la porta 8000, quindi imposta entrambe su 8000 come mostrato, oppure sostituisci 8000 con 8080 nei comandi di questa pagina.

Non eseguire mai il commit del file .env nel controllo versione. Il .gitignore del repository lo esclude già.

Add Your Products

Sostituisci il prodotto di esempio in internal/lib/products.go con i tuoi prodotti. Copia l’ID di ogni prodotto dalla sezione Products della 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 imposta solo il prezzo visualizzato dalla pagina dei prezzi, nell’unità minima della valuta: 9999 viene visualizzato come $99.99. Checkout applica il prezzo del prodotto in Dodo Payments.

Run the Development Server

make run

make run compila il server in bin/server e lo avvia. Per eseguire il server senza compilare prima un binario, esegui:

go run cmd/server/main.go

Apri http://localhost:8000 per visualizzare la pagina dei prezzi.

Vedrai una pagina dei prezzi a tema scuro che elenca i tuoi prodotti, pronta per gli acquisti.

Struttura del progetto

Il repository ha questa struttura:

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

Endpoint API

Il boilerplate include i seguenti endpoint preconfigurati:

Endpoint	Metodo	Descrizione
`/`	GET	Pagina dei prezzi che elenca i prodotti in `internal/lib/products.go`.
`/api/checkout`	POST	Crea una sessione di checkout. Invia `product_id`, oltre a `quantity` facoltativo (predefinito `1`) e `customer` (`email`, `name`, `phone`). Restituisce `session_id` e `checkout_url`.
`/api/webhook`	POST	Verifica e gestisce i webhook Dodo Payments. Restituisce `401` quando il controllo della firma non riesce.
`/api/customer-portal`	POST	Restituisce un link al Customer Portal in `portal_url`. Invia `customer_id` oppure `email` con un `name` facoltativo. Con la sola email, l’handler cerca il cliente e lo crea se non esiste.
`/health`	GET	Controllo dello stato. Restituisce `OK`.

Personalizzazione

Aggiornare le informazioni sui prodotti

Modifica internal/lib/products.go per cambiare:

ID prodotto (dalla sezione Products della dashboard Dodo Payments)
Nomi
Prezzi visualizzati nella pagina dei prezzi
Funzionalità
Descrizioni

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

Il template della pagina dei prezzi aggiunge un suffisso /mo a ogni prezzo e mostra Custom al posto del prezzo quando Price è pari o superiore a 100000. Per modificare questo comportamento, modifica templates/index.html.

Precompilare i dati del cliente

In .env, la funzione handleCheckout invia dati cliente codificati direttamente a /api/checkout. Sostituiscili con i dati dell’utente autenticato:

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 funzione handlePortal riutilizza questi dati cliente e ricorre allo stesso nome e alla stessa email di esempio. In un’app di produzione, inserisci questi valori dal tuo sistema di autenticazione in entrambe le funzioni.

Eventi webhook

internal/api/webhook.go verifica ogni richiesta con client.Webhooks.Unwrap e la chiave in DODO_PAYMENTS_WEBHOOK_KEY, quindi instrada l’evento in base al suo type. Questi eventi hanno un handler e ogni handler registra i dati dell’evento:

Evento	Descrizione
`payment.succeeded`	Attivato quando un pagamento va a buon fine
`payment.failed`	Attivato quando un tentativo di pagamento non va a buon fine
`subscription.active`	Attivato quando un abbonamento diventa attivo
`subscription.renewed`	Attivato quando un abbonamento si rinnova per il periodo di fatturazione successivo
`subscription.updated`	Attivato quando cambia un campo qualsiasi dell’abbonamento
`subscription.cancelled`	Attivato quando un abbonamento viene annullato

L’handler accetta anche subscription.on_hold, subscription.failed, subscription.expired e subscription.plan_changed senza eseguire alcuna azione e registra ogni altro tipo di evento come non gestito. Risponde con 200 a ogni evento verificato. Per tutti i tipi di evento, consulta la Guida agli eventi webhook. Aggiungi la tua logica di business alle funzioni handler per:

Aggiornare le autorizzazioni degli utenti nel database
Inviare email di conferma
Provisionare l’accesso ai prodotti digitali
Monitorare analisi e metriche

Testare i webhook in locale

Dodo Payments non può raggiungere localhost. Per ricevere webhook durante lo sviluppo, esponi il tuo server locale con un tunnel come ngrok:

ngrok http 8000

Nella Dashboard Dodo Payments, aggiungi un endpoint con l’URL di inoltro visualizzato da ngrok, seguito da /api/webhook:

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

Copia la chiave di firma dell’endpoint in DODO_PAYMENTS_WEBHOOK_KEY, quindi riavvia il server.

Deployment

Compilare per la produzione

make build compila il server in bin/server:

make build

Per compilare e avviare il binario senza make, esegui:

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

Eseguire il deployment su Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Dopo il deployment, aggiungi le variabili dal file .env alle impostazioni del progetto Vercel, perché .env non si trova nel repository. Quindi imposta l’endpoint webhook nella dashboard su https://yourdomain.com/api/webhook.

Docker

Crea un Dockerfile nella directory principale del progetto. La fase di build deve utilizzare Go 1.24.4 o versioni successive, in linea con 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’immagine finale copia templates/ accanto al binario, perché il server carica i template dalla directory di lavoro. Compila ed esegui l’immagine:

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

Il container resta in ascolto sul valore PORT di .env, quindi mantieni PORT=8000 in modo che corrisponda alla mappatura delle porte.

Considerazioni per la produzione

Prima di eseguire il deployment in produzione:

Imposta DODO_PAYMENTS_ENVIRONMENT su live_mode.
Utilizza una chiave API in modalità live dalla dashboard.
Indirizza l’endpoint webhook al tuo dominio di produzione e utilizza la chiave di firma di quell’endpoint.
Imposta DODO_PAYMENTS_RETURN_URL su una pagina del tuo dominio di produzione.
Servi ogni endpoint tramite HTTPS.

Risoluzione dei problemi

Build errors or missing dependencies

Verifica che go version indichi Go 1.24.4 o versioni successive, quindi scarica nuovamente i moduli:

go mod tidy
go mod download

Checkout session creation fails

Cause comuni:

L’ID prodotto non è valido. Verifica che esista nella sezione Products nella stessa modalità della tua chiave API.
La chiave API o DODO_PAYMENTS_ENVIRONMENT in .env è errata. Una chiave in modalità test richiede test_mode.
Per conoscere l’errore esatto, controlla i log del server. L’handler registra ogni richiesta non riuscita prima di restituire 500.

Webhooks not receiving events

Per i test locali, esponi il tuo server con ngrok:

ngrok http 8000

Imposta l’URL webhook nella dashboard Dodo Payments sull’URL ngrok. Quindi imposta DODO_PAYMENTS_WEBHOOK_KEY in .env sulla chiave di firma di quell’endpoint. Se il server registra webhook verification failed, la chiave non corrisponde all’endpoint.

Templates not loading

Il server carica templates/base.html e templates/index.html dalla directory di lavoro. Avvia il server dalla directory principale del progetto oppure modifica i percorsi dei template in cmd/server/main.go.

Approfondimenti

Go SDK

Documentazione completa dell’SDK Go

Webhooks Documentation

Scopri tutti gli eventi webhook e le best practice

Checkout Sessions

Approfondisci la configurazione delle sessioni di checkout

API Reference

Documentazione completa dell’API Dodo Payments

Supporto

Per ricevere assistenza sul boilerplate:

Fai domande nella community Discord.
Controlla il repository GitHub per problemi e aggiornamenti.
Contatta il team di supporto.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Panoramica

Caratteristiche

Requisiti

Avvio Rapido

Struttura del progetto

Endpoint API

Personalizzazione

Aggiornare le informazioni sui prodotti

Precompilare i dati del cliente

Eventi webhook

Testare i webhook in locale

Deployment

Compilare per la produzione

Eseguire il deployment su Vercel

Docker

Considerazioni per la produzione

Risoluzione dei problemi

Approfondimenti

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Supporto

GitHub Repository

​Panoramica

​Caratteristiche

​Requisiti

​Avvio Rapido

​Struttura del progetto

​Endpoint API

​Personalizzazione

​Aggiornare le informazioni sui prodotti

​Precompilare i dati del cliente

​Eventi webhook

​Testare i webhook in locale

​Deployment

​Compilare per la produzione

​Eseguire il deployment su Vercel

​Docker

​Considerazioni per la produzione

​Risoluzione dei problemi

​Approfondimenti

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Supporto

Panoramica

Caratteristiche

Requisiti

Avvio Rapido

Struttura del progetto

Endpoint API

Personalizzazione

Aggiornare le informazioni sui prodotti

Precompilare i dati del cliente

Eventi webhook

Testare i webhook in locale

Deployment

Compilare per la produzione

Eseguire il deployment su Vercel

Docker

Considerazioni per la produzione

Risoluzione dei problemi

Approfondimenti

Supporto