Plantilla Mínima de Next.js

Descripción General

La plantilla base minimalista de Next.js es una aplicación inicial con Dodo Payments ya conectado. Añade tus claves de API y los ID de tus productos para obtener una página de precios que abre el checkout, un endpoint de webhook para los eventos de pago y un enlace al Customer Portal.

Esta plantilla base utiliza el App Router de Next.js 16 con TypeScript, Tailwind CSS 4 y el adaptador @dodopayments/nextjs. Para añadir los mismos route handlers a una aplicación existente, consulta Next.js Adaptor.

Características

La plantilla base incluye:

Configuración rápida: pasa de clonar el repositorio a tener una página de precios en funcionamiento en unos cinco minutos.
Checkout: un flujo de checkout preconfigurado basado en @dodopayments/nextjs.
Página de precios: una página de precios con tema oscuro y estilos de Tailwind CSS.
Webhook Handler: un endpoint que verifica la firma de cada webhook y ejecuta tu código para el evento.
Customer Portal: un enlace en el encabezado que abre el Customer Portal, donde los clientes gestionan sus suscripciones.
TypeScript: definiciones y handlers de productos tipados.
Checkout precompletado: envía el nombre y el correo electrónico del cliente al checkout para que no tenga que volver a escribirlos.

Requisitos previos

Antes de comenzar, necesitas:

Node.js 20.9 o posterior, que es obligatorio para Next.js 16.
Una cuenta de Dodo Payments, para crear una clave de API y un secreto de firma de webhook en el dashboard.

Inicio rápido

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Regístrate en Dodo Payments y obtén tus credenciales en el dashboard:

API Key: crea una clave en Dashboard → Developer → API Keys.
Webhook Key: añade un endpoint en Dashboard → Developer → Webhooks y copia su secreto de firma. La URL del endpoint debe ser pública y utilizar HTTPS. Para recibir eventos en tu equipo, consulta Webhook Events.

Crea ambos mientras el interruptor de Live Mode de la barra lateral esté desactivado. Una clave del modo de prueba solo funciona con DODO_PAYMENTS_ENVIRONMENT=test_mode, y los pagos del modo de prueba no mueven dinero real.

Configure Environment Variables

Copia el archivo de ejemplo para crear un archivo .env en el directorio raíz:

cp .env.example .env

Configura los valores con tus credenciales de Dodo Payments:

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

Los route handlers leen estas variables:

DODO_PAYMENTS_API_KEY autentica los handlers de checkout y Customer Portal.
DODO_PAYMENTS_WEBHOOK_KEY verifica las firmas de los webhooks.
DODO_PAYMENTS_RETURN_URL indica dónde envía checkout al cliente después del pago.
DODO_PAYMENTS_ENVIRONMENT es test_mode o live_mode.

No confirmes tu archivo .env en el control de versiones. El archivo .gitignore del repositorio ya lo excluye.

Add Your Products

Sustituye los productos de ejemplo en src/lib/products.ts por los tuyos. Configura cada product_id con el ID de un producto incluido en Products en tu dashboard:

export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];

La página de precios muestra name, description, price y features de este archivo. Checkout cobra el precio configurado en el producto de Dodo Payments, así que mantén price sincronizado con él.

Run the Development Server

npm run dev

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

Estructura del proyecto

Los route handlers de checkout, Customer Portal y webhook se encuentran en src/app/api/:

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

Personalización

Actualizar la información del producto

Edita src/lib/products.ts para cambiar:

Los ID de los productos, desde Products en tu dashboard de Dodo Payments
Los precios
Las funciones
Las descripciones

Precompletar los datos del cliente

src/app/components/ProductCard.tsx envía un nombre y un correo electrónico codificados directamente en cada solicitud de checkout. Sustitúyelos por los datos del usuario que ha iniciado sesión:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Actualizar Customer Portal

El enlace de Customer Portal en src/app/components/Header.tsx abre /api/customer-portal con un ID de cliente codificado directamente. Sustitúyelo por el ID de cliente de Dodo Payments del usuario que ha iniciado sesión:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Para obtener un ID de cliente para realizar pruebas, completa una compra de prueba y copia el ID del cliente desde Customers en el dashboard. En producción, obtén el ID desde tu backend.

Eventos de webhook

El handler en src/app/api/webhook/route.ts verifica cada solicitud con DODO_PAYMENTS_WEBHOOK_KEY y, después, gestiona dos eventos:

onSubscriptionActive se ejecuta cuando una suscripción pasa a estar activa (subscription.active).
onPaymentSucceeded se ejecuta cuando un pago se realiza correctamente (payment.succeeded).

Añade tu lógica de negocio dentro de estos handlers:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

Para gestionar más eventos, añade sus handlers, como onSubscriptionCancelled. Next.js Adaptor contiene la lista de todos los handlers compatibles. Dodo Payments no puede acceder a localhost. Para el desarrollo local, utiliza un túnel como ngrok para exponer tu servidor local y usa la URL del túnel como endpoint de webhook.

Implementación

Compilar para producción

npm run build
npm start

Implementar en Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Añade las cuatro variables de entorno en el dashboard de Vercel y configura DODO_PAYMENTS_RETURN_URL con tu URL de producción.

Actualizar la URL del webhook

Después de la implementación, añade la URL de tu webhook de producción en Dodo Payments Dashboard, sustituyendo example.com por tu dominio:

https://example.com/api/webhook

Cada endpoint tiene su propio secreto de firma. Copia el secreto del nuevo endpoint en DODO_PAYMENTS_WEBHOOK_KEY en tu entorno de producción.

Solución de problemas

Module not found or build errors

Elimina node_modules y package-lock.json y, después, reinstala las dependencias:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Comprueba estas causas habituales:

El ID del producto no existe en tu dashboard de Dodo Payments.
La API key o DODO_PAYMENTS_ENVIRONMENT en .env es incorrecta. Una clave del modo de prueba solo funciona con test_mode.

Busca el error en la consola del navegador y en el terminal que ejecuta npm run dev.

Webhooks not receiving events

Para realizar pruebas locales, utiliza ngrok para exponer tu servidor:

ngrok http 3000

En tu Dodo dashboard, añade un endpoint con la URL HTTPS de ngrok seguida de /api/webhook. Copia el secreto de firma de ese endpoint en DODO_PAYMENTS_WEBHOOK_KEY dentro de tu archivo .env.

Customer portal link doesn't work

Sustituye el CUSTOMER_ID codificado directamente en src/app/components/Header.tsx por el ID de un cliente de tu dashboard de Dodo Payments.En producción, obtén el ID del cliente desde tu sistema de autenticación y tu base de datos.

Más información

Documentación de Dodo Payments
Documentación de Checkout Sessions
Documentación de Webhooks
Next.js Adaptor: opciones para los handlers Checkout, CustomerPortal y Webhooks

Soporte

Para obtener ayuda con la plantilla base:

Haz preguntas en la comunidad de Discord.
Informa de problemas y sigue las novedades en el repositorio de GitHub.
Envía un correo electrónico al equipo de soporte.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Descripción General

Características

Requisitos previos

Inicio rápido

Estructura del proyecto

Personalización

Actualizar la información del producto

Precompletar los datos del cliente

Actualizar Customer Portal

Eventos de webhook

Implementación

Compilar para producción

Implementar en Vercel

Actualizar la URL del webhook

Solución de problemas

Más información

Soporte

​Descripción General

​Características

​Requisitos previos

​Inicio rápido

​Estructura del proyecto

​Personalización

​Actualizar la información del producto

​Precompletar los datos del cliente

​Actualizar Customer Portal

​Eventos de webhook

​Implementación

​Compilar para producción

​Implementar en Vercel

​Actualizar la URL del webhook

​Solución de problemas

​Más información

​Soporte

Descripción General

Características

Requisitos previos

Inicio rápido

Estructura del proyecto

Personalización

Actualizar la información del producto

Precompletar los datos del cliente

Actualizar Customer Portal

Eventos de webhook

Implementación

Compilar para producción

Implementar en Vercel

Actualizar la URL del webhook

Solución de problemas

Más información

Soporte