> ## 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.

# Adaptador de Express

> Aprende a integrar Dodo Payments con tu proyecto Express App Router utilizando nuestro Adaptador de Express. Cubre el proceso de pago, el portal del cliente, webhooks y la configuración de un entorno seguro.

<CardGroup cols={2}>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integra el flujo de pago de Dodo Payments en tu aplicación Express.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Permite que los clientes gestionen sus suscripciones y detalles.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Recibe y procesa eventos webhook de Dodo Payments.
  </Card>
</CardGroup>

## Instalación

<Steps>
  <Step title="Install the package">
    Ejecuta el siguiente comando en la raíz de tu proyecto:

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    Crea un archivo <code>.env</code> en la raíz de tu proyecto:

    ```env expandable theme={null}
    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
    ```

    <Warning>
      Nunca subas tu archivo <code>.env</code> o secretos al control de versiones.
    </Warning>
  </Step>
</Steps>

## Ejemplos de Manejadores de Rutas

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      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).
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      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
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      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"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Usa este controlador para permitir que los clientes gestionen sus suscripciones y detalles a través del portal de clientes de Dodo Payments.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

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

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      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
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Usa este controlador para recibir y procesar de forma segura los eventos webhook de Dodo Payments en tu aplicación Express.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Manejador de Ruta de Checkout

<Info>
  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.
</Info>

* **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.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Parámetros de consulta compatibles

    <ParamField query="productId" type="string" required>
      Identificador del producto (por ejemplo, <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField query="quantity" type="integer">
      Cantidad del producto.
    </ParamField>

    <ParamField query="fullName" type="string">
      Nombre completo del cliente.
    </ParamField>

    <ParamField query="firstName" type="string">
      Nombre de pila del cliente.
    </ParamField>

    <ParamField query="lastName" type="string">
      Apellido del cliente.
    </ParamField>

    <ParamField query="email" type="string">
      Correo electrónico del cliente.
    </ParamField>

    <ParamField query="country" type="string">
      País del cliente.
    </ParamField>

    <ParamField query="addressLine" type="string">
      Dirección del cliente.
    </ParamField>

    <ParamField query="city" type="string">
      Ciudad del cliente.
    </ParamField>

    <ParamField query="state" type="string">
      Estado/provincia del cliente.
    </ParamField>

    <ParamField query="zipCode" type="string">
      Código postal del cliente.
    </ParamField>

    <ParamField query="disableFullName" type="boolean">
      Deshabilita el campo de nombre completo.
    </ParamField>

    <ParamField query="disableFirstName" type="boolean">
      Deshabilita el campo de nombre.
    </ParamField>

    <ParamField query="disableLastName" type="boolean">
      Deshabilita el campo de apellido.
    </ParamField>

    <ParamField query="disableEmail" type="boolean">
      Deshabilita el campo de correo electrónico.
    </ParamField>

    <ParamField query="disableCountry" type="boolean">
      Deshabilita el campo de país.
    </ParamField>

    <ParamField query="disableAddressLine" type="boolean">
      Deshabilita el campo de dirección.
    </ParamField>

    <ParamField query="disableCity" type="boolean">
      Deshabilita el campo de ciudad.
    </ParamField>

    <ParamField query="disableState" type="boolean">
      Deshabilita el campo de estado.
    </ParamField>

    <ParamField query="disableZipCode" type="boolean">
      Deshabilita el campo de código postal.
    </ParamField>

    <ParamField query="paymentCurrency" type="string">
      Especifica la moneda de pago (por ejemplo, <code>USD</code>).
    </ParamField>

    <ParamField query="showCurrencySelector" type="boolean">
      Muestra el selector de moneda.
    </ParamField>

    <ParamField query="paymentAmount" type="integer">
      Especifica el monto del pago (por ejemplo, <code>1000</code> para \$10.00).
    </ParamField>

    <ParamField query="showDiscounts" type="boolean">
      Muestra los campos de descuento.
    </ParamField>

    <ParamField query="metadata_*" type="string">
      Cualquier parámetro de consulta que comience con <code>metadata\_</code> se pasará como metadatos.
    </ParamField>

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

    ### Formato de Respuesta

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="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](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Cuerpo de solicitud para un producto de suscripción](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Formato de Respuesta

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="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](https://docs.dodopayments.com/developer-resources/checkout-session) 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:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## 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

<ParamField query="customer_id" type="string" required>
  El ID del cliente para la sesión del portal (por ejemplo, <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField query="send_email" type="boolean">
  Si se establece en <code>true</code>, envía un correo al cliente con el enlace del portal.
</ParamField>

<Warning>
  Devuelve 400 si falta <code>customer\_id</code>.
</Warning>

## 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 <code>webhookKey</code>. 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

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  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>;
  ```
</CodeGroup>

***

## 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.).
```