> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Plantilla Go
> Clona un servidor Go mínimo que crea sesiones de checkout de Dodo Payments, verifica webhooks y abre el Customer Portal con el SDK dodopayments-go.
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`](/developer-resources/sdks/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
```bash theme={null}
git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate
```
```bash theme={null}
make install
```
`make install` ejecuta `go mod download` y luego `go mod tidy`. Para descargar los módulos sin `make`, ejecuta:
```bash theme={null}
go mod download
```
Regístrate en [Dodo Payments](https://dodopayments.com/) y copia ambas claves desde el dashboard:
* **API Key:** [Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
* **Webhook Key:** [Developer → Webhooks](https://app.dodopayments.com/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](#testing-webhooks-locally).
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.
Crea un archivo `.env` en la raíz del proyecto a partir de la plantilla:
```bash theme={null}
cp .env.example .env
```
Establece estos valores en `.env`:
```bash .env theme={null}
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.
Reemplaza el producto de ejemplo en `internal/lib/products.go` por tus productos. Copia el ID de cada producto desde **Products** en el dashboard:
```go theme={null}
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.
```bash theme={null}
make run
```
`make run` compila el servidor en `bin/server` y lo inicia. Para ejecutar el servidor sin compilar primero un binario, ejecuta:
```bash theme={null}
go run cmd/server/main.go
```
Abre [http://localhost:8000](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:
```text theme={null}
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
```go theme={null}
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:
```javascript theme={null}
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](/developer-resources/webhooks/intents/webhook-events-guide).
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](https://ngrok.com/):
```bash theme={null}
ngrok http 8000
```
En el [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks), añade un endpoint con la URL de reenvío que muestra ngrok, seguida de `/api/webhook`:
```text theme={null}
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`:
```bash theme={null}
make build
```
Para compilar e iniciar el binario sin `make`, ejecuta:
```bash theme={null}
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](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`:
```dockerfile theme={null}
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:
```bash theme={null}
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
Comprueba que `go version` indique Go 1.24.4 o posterior y vuelve a descargar los módulos:
```bash theme={null}
go mod tidy
go mod download
```
**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`.
Para realizar pruebas locales, expón tu servidor con [ngrok](https://ngrok.com):
```bash theme={null}
ngrok http 8000
```
Establece la URL del webhook en tu [dashboard de Dodo Payments](https://app.dodopayments.com/developer/webhooks) 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.
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
Documentación completa del SDK de Go
Conoce todos los eventos de webhook y las buenas prácticas
Análisis detallado de la configuración de las sesiones de checkout
Documentación completa de la API de Dodo Payments
## Soporte
Para obtener ayuda con el boilerplate:
* Haz preguntas en la [comunidad de Discord](https://discord.gg/bYqAp4ayYh).
* Consulta el [repositorio de GitHub](https://github.com/dodopayments/go-boilerplate) para ver incidencias y actualizaciones.
* Contacta con el [equipo de soporte](mailto:support@dodopayments.com).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.