Plantilla Go

GitHub Repository

Boilerplate mínimo de Go + Dodo Payments

Descripción general

El boilerplate de Go es un servidor Go mínimo que vende tus productos de Dodo Payments desde una página de precios. Crea sesiones de checkout, verifica y gestiona webhooks, y abre el Customer Portal. Clónalo como punto de partida para tu propio backend de Go.

El boilerplate requiere Go 1.24.4 o posterior, la versión establecida en su go.mod. Utiliza un diseño con cmd, internal y templates, renderiza la página de precios con plantillas HTML de Go y llama a la API de Dodo Payments mediante el SDK dodopayments-go.

Características

Configuración rápida: clona el repositorio, añade tus API keys a .env e inicia el servidor con make run.
Integración de pagos: un flujo de checkout que crea sesiones de checkout con el SDK dodopayments-go.
UI moderna: una página de precios con tema oscuro creada con plantillas HTML de Go y Tailwind CSS.
Gestión de webhooks: verifica la firma de cada webhook antes de procesar el evento.
Customer Portal: gestión de suscripciones mediante autoservicio a través del Customer Portal.
Buenas prácticas de Go: una estructura de proyecto limpia con cmd, internal y templates.
Checkout precompletado: envía el nombre y el email del cliente al checkout para que no tenga que escribirlos de nuevo.

Requisitos previos

Antes de comenzar, necesitas:

Go 1.24.4 o posterior. Comprueba tu versión con go version.
Una cuenta de Dodo Payments, para crear una API key y una clave de firma de webhook en el dashboard.
Al menos un producto, creado en Products en el dashboard.

Inicio rápido

Clona el repositorio

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

Instala las dependencias

make install

make install ejecuta go mod download y luego go mod tidy. Para descargar los módulos sin make, ejecuta:

go mod download

Get API Credentials

Regístrate en Dodo Payments y copia ambas claves desde el dashboard:

API Key: Developer → API Keys
Webhook Key: Developer → Webhooks. Cada endpoint de webhook tiene su propia clave de firma. Para crear un endpoint que llegue a tu servidor local, consulta Probar webhooks localmente.

Crea ambas claves en modo de prueba mientras desarrollas. Para cambiar al modo de prueba, desactiva el interruptor Live Mode en la barra lateral del dashboard.

Configure Environment Variables

Crea un archivo .env en la raíz del proyecto a partir de la plantilla:

cp .env.example .env

Establece estos valores en .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

El servidor lee estas variables al iniciarse:

Variable	Obligatoria	Valor predeterminado	Propósito
`DODO_PAYMENTS_API_KEY`	Sí	Ninguno	Autentica las solicitudes a la API de Dodo Payments.
`DODO_PAYMENTS_WEBHOOK_KEY`	Sí	Ninguno	Verifica la firma de los webhooks entrantes.
`DODO_PAYMENTS_RETURN_URL`	No	`http://localhost:8080`	La URL a la que checkout envía al cliente después del pago.
`DODO_PAYMENTS_ENVIRONMENT`	No	`test_mode`	`test_mode` o `live_mode`.
`PORT`	No	`8000`	El puerto en el que escucha el servidor.

El servidor se cierra al iniciarse si falta alguna de las claves obligatorias. .env.example establece PORT y DODO_PAYMENTS_RETURN_URL en el puerto 8080. Esta página utiliza el puerto 8000, así que establece ambos en 8000 como se muestra, o reemplaza 8000 por 8080 en los comandos de esta página.

Nunca hagas commit de tu archivo .env en el control de versiones. El .gitignore del repositorio ya lo excluye.

Add Your Products

Reemplaza el producto de ejemplo en internal/lib/products.go por tus productos. Copia el ID de cada producto desde Products en el 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 establece únicamente el precio que muestra la página de precios, en la unidad monetaria más pequeña: 9999 se muestra como $99.99. Checkout cobra el precio del producto en Dodo Payments.

Run the Development Server

make run

make run compila el servidor en bin/server y lo inicia. Para ejecutar el servidor sin compilar primero un binario, ejecuta:

go run cmd/server/main.go

Abre http://localhost:8000 para ver tu página de precios.

Verás una página de precios con tema oscuro que muestra tus productos, lista para realizar compras.

Estructura del proyecto

El repositorio tiene esta estructura:

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 de la API

El boilerplate incluye los siguientes endpoints preconfigurados:

Endpoint	Método	Descripción
`/`	GET	Página de precios que muestra los productos de `internal/lib/products.go`.
`/api/checkout`	POST	Crea una sesión de checkout. Envía `product_id`, además de `quantity` opcional (valor predeterminado `1`) e `customer` (`email`, `name`, `phone`). Devuelve `session_id` y `checkout_url`.
`/api/webhook`	POST	Verifica y gestiona los webhooks de Dodo Payments. Devuelve `401` cuando falla la comprobación de la firma.
`/api/customer-portal`	POST	Devuelve un enlace al Customer Portal en `portal_url`. Envía `customer_id` o `email` con un `name` opcional. Si solo se proporciona un email, el handler busca al cliente y crea uno si no existe.
`/health`	GET	Health check. Devuelve `OK`.

Personalización

Actualizar la información de los productos

Edita internal/lib/products.go para cambiar:

IDs de productos (desde Products en tu dashboard de Dodo Payments)
Nombres
Precios mostrados en la página de precios
Funciones
Descripciones

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

La plantilla de la página de precios añade un sufijo /mo a cada precio y muestra Custom en lugar de un precio cuando Price es 100000 o superior. Para cambiar esto, edita templates/index.html.

Precompletar los datos del cliente

En .env, la función handleCheckout envía datos de cliente codificados directamente a /api/checkout. Sustitúyela por los datos de tu usuario autenticado:

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 función handlePortal reutiliza estos datos del cliente y recurre al mismo nombre y email de ejemplo. En una aplicación de producción, inyecta estos valores desde tu sistema de autenticación en ambas funciones.

Eventos de webhook

internal/api/webhook.go verifica cada solicitud con client.Webhooks.Unwrap y la clave de DODO_PAYMENTS_WEBHOOK_KEY, y luego enruta el evento según su type. Estos eventos tienen un handler, y cada handler registra los datos del evento:

Evento	Descripción
`payment.succeeded`	Se activa cuando un pago tiene éxito
`payment.failed`	Se activa cuando falla un intento de pago
`subscription.active`	Se activa cuando una suscripción pasa a estar activa
`subscription.renewed`	Se activa cuando una suscripción se renueva para el siguiente periodo de facturación
`subscription.updated`	Se activa cuando cambia cualquier campo de una suscripción
`subscription.cancelled`	Se activa cuando se cancela una suscripción

El handler también acepta subscription.on_hold, subscription.failed, subscription.expired e subscription.plan_changed sin realizar ninguna acción, y registra cualquier otro tipo de evento como no gestionado. Responde con 200 a cada evento verificado. Para consultar todos los tipos de evento, consulta la Guía de eventos de webhook. Añade tu lógica de negocio a las funciones handler para:

Actualizar los permisos de usuario en tu base de datos
Enviar emails de confirmación
Provisionar acceso a productos digitales
Realizar un seguimiento de analytics y métricas

Probar webhooks localmente

Dodo Payments no puede acceder a localhost. Para recibir webhooks durante el desarrollo, expón tu servidor local con un túnel como ngrok:

ngrok http 8000

En el Dodo Payments Dashboard, añade un endpoint con la URL de reenvío que muestra ngrok, seguida de /api/webhook:

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

Copia la clave de firma del endpoint en DODO_PAYMENTS_WEBHOOK_KEY y reinicia el servidor.

Implementación

Compilar para producción

make build compila el servidor en bin/server:

make build

Para compilar e iniciar el binario sin make, ejecuta:

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

Implementar en Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Después de implementar, añade las variables de tu archivo .env a la configuración del proyecto de Vercel, porque .env no está en el repositorio. Después, establece tu endpoint de webhook en el dashboard como https://yourdomain.com/api/webhook.

Docker

Crea un Dockerfile en la raíz del proyecto. La etapa de compilación debe utilizar Go 1.24.4 o posterior para coincidir 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"]

La imagen final copia templates/ junto al binario, porque el servidor carga las plantillas desde el directorio de trabajo. Compila y ejecuta la imagen:

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

El contenedor escucha en el valor PORT de .env, así que mantén PORT=8000 para que coincida con la asignación de puertos.

Consideraciones para producción

Antes de implementar en producción:

Establece DODO_PAYMENTS_ENVIRONMENT en live_mode.
Utiliza una API key de modo live del dashboard.
Dirige el endpoint de webhook a tu dominio de producción y utiliza la clave de firma de ese endpoint.
Establece DODO_PAYMENTS_RETURN_URL en una página de tu dominio de producción.
Sirve todos los endpoints mediante HTTPS.

Solución de problemas

Build errors or missing dependencies

Comprueba que go version indique Go 1.24.4 o posterior y vuelve a descargar los módulos:

go mod tidy
go mod download

Checkout session creation fails

Causas comunes:

El ID del producto no es válido. Comprueba que exista en Products en el mismo modo que tu API key.
La API key o DODO_PAYMENTS_ENVIRONMENT en .env es incorrecta. Una clave de modo de prueba necesita test_mode.
Para consultar el error exacto, revisa los logs del servidor. El handler registra cada solicitud fallida antes de devolver 500.

Webhooks not receiving events

Para realizar pruebas locales, expón tu servidor con ngrok:

ngrok http 8000

Establece la URL del webhook en tu dashboard de Dodo Payments como la URL de ngrok. Después, establece DODO_PAYMENTS_WEBHOOK_KEY en .env como la clave de firma de ese endpoint. Si los logs del servidor muestran webhook verification failed, la clave no coincide con la del endpoint.

Templates not loading

El servidor carga templates/base.html e templates/index.html desde el directorio de trabajo. Inicia el servidor desde la raíz del proyecto o cambia las rutas de las plantillas en cmd/server/main.go.

Más información

Go SDK

Documentación completa del SDK de Go

Webhooks Documentation

Conoce todos los eventos de webhook y las buenas prácticas

Checkout Sessions

Análisis detallado de la configuración de las sesiones de checkout

API Reference

Documentación completa de la API de Dodo Payments

Soporte

Para obtener ayuda con el boilerplate:

Haz preguntas en la comunidad de Discord.
Consulta el repositorio de GitHub para ver incidencias y actualizaciones.
Contacta con el equipo de soporte.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Descripción general

Características

Requisitos previos

Inicio rápido

Estructura del proyecto

Endpoints de la API

Personalización

Actualizar la información de los productos

Precompletar los datos del cliente

Eventos de webhook

Probar webhooks localmente

Implementación

Compilar para producción

Implementar en Vercel

Docker

Consideraciones para producción

Solución de problemas

Más información

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Soporte

GitHub Repository

​Descripción general

​Características

​Requisitos previos

​Inicio rápido

​Estructura del proyecto

​Endpoints de la API

​Personalización

​Actualizar la información de los productos

​Precompletar los datos del cliente

​Eventos de webhook

​Probar webhooks localmente

​Implementación

​Compilar para producción

​Implementar en Vercel

​Docker

​Consideraciones para producción

​Solución de problemas

​Más información

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Soporte

Descripción general

Características

Requisitos previos

Inicio rápido

Estructura del proyecto

Endpoints de la API

Personalización

Actualizar la información de los productos

Precompletar los datos del cliente

Eventos de webhook

Probar webhooks localmente

Implementación

Compilar para producción

Implementar en Vercel

Docker

Consideraciones para producción

Solución de problemas

Más información

Soporte