Adaptador de Express

Checkout Handler

Integra el flujo de pago de Dodo Payments en tu aplicación Express.

Customer Portal

Permite que los clientes gestionen sus suscripciones y detalles.

Webhooks

Recibe y procesa eventos webhook de Dodo Payments.

Instalación

Install the package

Ejecuta el siguiente comando en la raíz de tu proyecto:

npm install @dodopayments/express

Set up environment variables

Crea un archivo .env en la raíz de tu proyecto:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Nunca subas tu archivo .env o secretos al control de versiones.

Ejemplos de Manejadores de Rutas

Checkout Handler
Customer Portal Handler
Webhook Handler

Usa este controlador para integrar el flujo de pago de Dodo Payments en tu aplicación Express. Admite flujos de pago estáticos (GET), dinámicos (POST) y de sesión (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "test@example.com",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

Usa este controlador para permitir que los clientes gestionen sus suscripciones y detalles a través del portal de clientes de Dodo Payments.

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}))

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Usa este controlador para recibir y procesar de forma segura los eventos webhook de Dodo Payments en tu aplicación Express.

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook',Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        // handle the payload
    },
    // ... other event handlers for granular control
}))

Manejador de Ruta de Checkout

Dodo Payments admite tres tipos de flujos de pago para integrar pagos en tu sitio web; este adaptador admite todos los tipos de flujos de pago.

Enlaces de Pago Estáticos: URLs instantáneamente compartibles para la recolección de pagos rápida y sin código.
Enlaces de Pago Dinámicos: Genera programáticamente enlaces de pago con detalles personalizados utilizando la API o SDKs.
Sesiones de Checkout: Crea experiencias de checkout seguras y personalizables con carritos de productos preconfigurados y detalles del cliente.

Static Checkout (GET)

Parámetros de consulta compatibles

string

requerido

Identificador del producto (por ejemplo, ?productId=pdt_nZuwz45WAs64n3l07zpQR).

integer

Cantidad del producto.

string

Nombre completo del cliente.

string

Nombre de pila del cliente.

string

Apellido del cliente.

string

Correo electrónico del cliente.

string

País del cliente.

string

Dirección del cliente.

string

Ciudad del cliente.

string

Estado/provincia del cliente.

string

Código postal del cliente.

boolean

Deshabilita el campo de nombre completo.

boolean

Deshabilita el campo de nombre.

boolean

Deshabilita el campo de apellido.

boolean

Deshabilita el campo de correo electrónico.

boolean

Deshabilita el campo de país.

boolean

Deshabilita el campo de dirección.

boolean

Deshabilita el campo de ciudad.

boolean

Deshabilita el campo de estado.

boolean

Deshabilita el campo de código postal.

string

Especifica la moneda de pago (por ejemplo, USD).

boolean

Muestra el selector de moneda.

integer

Especifica el monto del pago (por ejemplo, 1000 para $10.00).

boolean

Muestra los campos de descuento.

string

Cualquier parámetro de consulta que comience con metadata_ se pasará como metadatos.

Si falta productId, el controlador devuelve una respuesta 400. Los parámetros de consulta inválidos también resultan en una respuesta 400.

Formato de Respuesta

El checkout estático devuelve una respuesta JSON con la URL de checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Dynamic Checkout (POST)

Envía los parámetros como un cuerpo JSON en una solicitud POST.
Admite pagos únicos y recurrentes.
Para una lista completa de los campos compatibles en el cuerpo POST, consulta:
- Cuerpo de solicitud para un producto de pago único
- Cuerpo de solicitud para un producto de suscripción

Formato de Respuesta

El checkout dinámico devuelve una respuesta JSON con la URL de checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Checkout Sessions (POST)

Las sesiones de pago ofrecen una experiencia de pago alojada y más segura que maneja todo el flujo de pago tanto para compras únicas como para suscripciones con control total de personalización.Consulta la Guía de Integración de Sesiones de Checkout para más detalles y una lista completa de los campos soportados.

Formato de Respuesta

Las sesiones de checkout devuelven una respuesta JSON con la URL de checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

Manejador de Ruta del Portal del Cliente

El Manejador de Ruta del Portal del Cliente te permite integrar sin problemas el portal del cliente de Dodo Payments en tu aplicación Express.

Parámetros de consulta

string

requerido

El ID del cliente para la sesión del portal (por ejemplo, ?customer_id=cus_123).

boolean

Si se establece en true, envía un correo al cliente con el enlace del portal.

Devuelve 400 si falta customer_id.

Manejador de Ruta de Webhook

Método: Solo se admiten solicitudes POST. Otros métodos devuelven 405.
Verificación de Firma: Verifica la firma del webhook utilizando webhookKey. Devuelve 401 si la verificación falla.
Validación de Carga Útil: Validada con Zod. Devuelve 400 para cargas útiles inválidas.
Manejo de Errores:
- 401: Firma inválida
- 400: Carga útil inválida
- 500: Error interno durante la verificación
Enrutamiento de Eventos: Llama al manejador de eventos apropiado según el tipo de carga útil.

Controladores de eventos webhook compatibles

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

Solicitud para LLM

Eres un asistente experto en desarrollo de Express.js. Tu tarea es guiar a un usuario a través de la integración del adaptador @dodopayments/express en su proyecto existente de Express.js.

El adaptador @dodopayments/express proporciona manejadores de ruta para las funcionalidades de Checkout, Portal del Cliente y Webhook de Dodo Payments, diseñados para integrarse directamente en una aplicación Express.

Primero, instala el paquete necesario. Usa el gestor de paquetes apropiado para el proyecto del usuario (npm, yarn o bun):

npm install @dodopayments/express

---

Aquí te mostramos cómo deberías estructurar tu respuesta:

1. Pregunta al usuario qué funcionalidades desea integrar.

"¿Qué partes del adaptador @dodopayments/express te gustaría integrar en tu proyecto? Puedes elegir una o más de las siguientes:

- Manejador de Ruta de Checkout (para manejar checkouts de productos)
- Manejador de Ruta del Portal del Cliente (para gestionar suscripciones/detalles del cliente)
- Manejador de Ruta de Webhook (para recibir eventos de webhook de Dodo Payments)
- Todo (integrar los tres)"

---

2. Según la selección del usuario, proporciona pasos de integración detallados para cada funcionalidad elegida.

---

**Si se selecciona el Manejador de Ruta de Checkout:**

**Propósito**: Este manejador gestiona diferentes tipos de flujos de checkout. Todos los tipos de checkout (estáticos, dinámicos y sesiones) devuelven respuestas JSON con URLs de checkout para manejo programático.

**Integración**:
Crea rutas en tu aplicación Express para checkout estático (GET), dinámico (POST) y sesiones de checkout (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// Para sesiones de checkout
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Opciones de Configuración:

    bearerToken: Tu clave API de Dodo Payments (se recomienda almacenarla en la variable de entorno DODO_PAYMENTS_API_KEY).

    returnUrl (opcional): URL para redirigir al usuario después de un checkout exitoso.

    environment: "test_mode" o "live_mode"

    type: "static" (GET), "dynamic" (POST), o "session" (POST)

GET (checkout estático) espera parámetros de consulta:

    productId (requerido)

    quantity, campos del cliente (fullName, email, etc.), y metadatos (metadata_*) son opcionales.

    Devuelve: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (checkout dinámico) espera un cuerpo JSON con detalles de pago (único o suscripción). Consulta la documentación para el esquema completo del POST:

    Pagos únicos: https://docs.dodopayments.com/api-reference/payments/post-payments

    Suscripciones: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Devuelve: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (sesiones de checkout) - (Recomendado) Una experiencia de checkout más personalizable. Devuelve JSON con checkout_url: Los parámetros se envían como un cuerpo JSON. Soporta tanto pagos únicos como recurrentes. Devuelve: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Para una lista completa de los campos soportados, consulta:

  Guía de Integración de Sesiones de Checkout: https://docs.dodopayments.com/developer-resources/checkout-session

Si se selecciona el Manejador de Ruta del Portal del Cliente:

Propósito: Esta ruta permite a los clientes gestionar sus suscripciones a través del portal de Dodo Payments.

Integración:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Parámetros de Consulta:

    customer_id (requerido): por ejemplo, ?customer_id=cus_123

    send_email (opcional): si es verdadero, se envía al cliente el enlace del portal

Devuelve 400 si falta customer_id.

Si se selecciona el Manejador de Ruta de Webhook:

Propósito: Procesa eventos de webhook entrantes de Dodo Payments para activar eventos en tu aplicación.

Integración:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Manejar carga útil genérica
  },
  // También puedes proporcionar manejadores específicos para cada tipo de evento a continuación
}));

Características:

    Solo se permite el método POST — otros devuelven 405

    La verificación de firma se realiza utilizando webhookKey. Devuelve 401 si es inválido.

    Validación de carga útil basada en Zod. Devuelve 400 si el esquema es inválido.

    Todos los manejadores son funciones asíncronas.

Manejadores de Eventos de Webhook Soportados:

Puedes pasar cualquiera de los siguientes manejadores:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

Configuración de Variables de Entorno:

Asegúrate de definir estas variables de entorno en tu proyecto:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Utiliza estas en tu código como:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Nota de Seguridad: NO cometas secretos en el control de versiones. Usa archivos .env localmente y gestores de secretos en entornos de despliegue (por ejemplo, AWS, Vercel, Heroku, etc.).

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Handler

Customer Portal

Webhooks

Instalación

Ejemplos de Manejadores de Rutas

Manejador de Ruta de Checkout

Parámetros de consulta compatibles

Formato de Respuesta

Formato de Respuesta

Formato de Respuesta

Manejador de Ruta del Portal del Cliente

Parámetros de consulta

Manejador de Ruta de Webhook

Controladores de eventos webhook compatibles

Solicitud para LLM

Checkout Handler

Customer Portal

Webhooks

​Instalación

​Ejemplos de Manejadores de Rutas

​Manejador de Ruta de Checkout

​Parámetros de consulta compatibles

​Formato de Respuesta

​Formato de Respuesta

​Formato de Respuesta

​Manejador de Ruta del Portal del Cliente

​Parámetros de consulta

​Manejador de Ruta de Webhook

​Controladores de eventos webhook compatibles

​Solicitud para LLM

Instalación

Ejemplos de Manejadores de Rutas

Manejador de Ruta de Checkout

Parámetros de consulta compatibles

Formato de Respuesta

Formato de Respuesta

Formato de Respuesta

Manejador de Ruta del Portal del Cliente

Parámetros de consulta

Manejador de Ruta de Webhook

Controladores de eventos webhook compatibles

Solicitud para LLM