Saltar al contenido principal

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.
Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

Prerequisites

1

Dodo Payments Account

You’ll need an active Dodo Payments merchant account with API access.
2

API Credentials

Generate your API credentials from the Dodo Payments dashboard:
3

Products Setup

Create your products in the Dodo Payments dashboard before implementing checkout sessions.

Creating Your First Checkout Session

import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

API Response

All methods above return the same response structure:
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
1

Get the checkout URL

Extract the checkout_url from the API response.
2

Redirect your customer

Direct your customer to the checkout URL to complete their purchase.
// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');
Alternative Integration Options: Instead of redirecting, you can embed the checkout directly in your page using Overlay Checkout (modal overlay) or Inline Checkout (fully embedded). Both options use the same checkout session URL.
3

Handle the return

After payment, customers are redirected to your return_url with query parameters including payment/subscription ID, status, customer email, and any license keys. See the return_url parameter docs for the full list.

Request Body

Required Fields

Essential fields needed for every checkout session

Optional Fields

Additional configuration to customize your checkout experience

Required Fields

product_cart
array
requerido
Array of products to include in the checkout session. Each product must have a valid product_id from your Dodo Payments dashboard.
Mixed Checkout: You can combine one-time payment products and subscription products in the same checkout session. This enables powerful use cases like setup fees with subscriptions, hardware bundles with SaaS, and more.
Encuentra tus IDs de Producto: Puedes encontrar los IDs de producto en tu panel de Dodo Payments bajo Productos → Ver Detalles, o utilizando la API de Listado de Productos.

Campos Opcionales

Configura estos campos para personalizar la experiencia de compra y añadir lógica empresarial a tu flujo de pago.
customer
object
Información del cliente. Puedes adjuntar un cliente existente usando su ID o crear un nuevo registro de cliente durante la compra.
Adjuntar un cliente existente a la sesión de compra usando su ID.
billing_address
object
Información de la dirección de facturación para cálculo preciso de impuestos, prevención de fraudes y cumplimiento regulatorio.
Cuando confirm está configurado en true, todos los campos de dirección de facturación se vuelven obligatorios para la creación exitosa de la sesión.
allowed_payment_method_types
array
Controla qué métodos de pago están disponibles para los clientes durante la compra. Esto ayuda a optimizar para mercados específicos o requisitos de negocio.Opciones Disponibles: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal, sunbit
Crítico: Siempre incluya credit y debit como opciones de respaldo para prevenir fallas en la compra cuando los métodos de pago preferidos no están disponibles.
Ejemplo:
["apple_pay", "google_pay", "credit", "debit"]
billing_currency
string
Sobrescriba la selección de moneda predeterminada con una moneda de facturación fija. Utiliza códigos de moneda ISO 4217.Monedas soportadas: USD, EUR, GBP, CAD, AUD, INR, y másEjemplo: "USD" para dólares estadounidenses, "EUR" para euros
Este campo solo es efectivo cuando el precio adaptativo está habilitado. Si el precio adaptativo está deshabilitado, se usará la moneda predeterminada del producto.
show_saved_payment_methods
boolean
predeterminado:"false"
Mostrar métodos de pago previamente guardados para clientes recurrentes, mejorando la velocidad de la compra y la experiencia del usuario.
return_url
string
URL para redirigir a los clientes tras la finalización del pago. Dodo Payments añade los siguientes parámetros de consulta a tu URL al redirigir:
ParámetroTipoCondición
payment_idstringSiempre presente para pagos únicos
subscription_idstringSiempre presente para pagos de suscripción
statusstringSiempre presente
license_keystringPresente si el producto tiene claves de licencia habilitadas. Separado por comas si hay múltiples claves
emailstringPresente si el cliente tiene un correo electrónico registrado
Ejemplos de URLs de redirección:
# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com
Utilice los parámetros de consulta license_key e email para mostrar claves de licencia o enviar una confirmación inmediatamente en tu página de retorno, sin necesidad de una llamada API adicional.
cancel_url
string
URL para redirigir a los clientes cuando hacen clic en el botón de regreso o cancelan la sesión de compra. Si no se proporciona, no se mostrará el botón de regreso.
Establece un cancel_url para dar a los clientes una forma clara de regresar a tu sitio sin completar la compra. Esto mejora la experiencia de compra y reduce fricciones.
confirm
boolean
predeterminado:"false"
Si es verdadero, finaliza todos los detalles de la sesión inmediatamente. La API lanzará un error si falta información requerida.
discount_codes
array
Aplicar uno o más códigos de descuento acumulativos a la sesión de compra. Los códigos se aplican en el orden del array (el primer código reduce el precio base, el segundo reduce el precio ya descontado, y así sucesivamente), hasta un máximo de 20 códigos por sesión.
discount_codes: ['WELCOME10', 'BLACKFRIDAY20']
El campo singular discount_code a continuación está obsoleto pero aún es plenamente compatible: las integraciones existentes continúan funcionando sin cambios. No se puede combinar con discount_codes en la misma solicitud. Migrar a discount_codes cuando sea conveniente para aprovechar el apilamiento.
discount_code
string
obsoleto
Obsoleto — prefiera discount_codes para nuevas integraciones. Este campo aún funciona para compatibilidad con versiones anteriores, pero no se puede combinar con discount_codes en la misma solicitud.
metadata
object
Pares de clave-valor personalizados para almacenar información adicional sobre la sesión.
force_3ds
boolean
Sobrescribe el comportamiento de 3DS predeterminado del comerciante para esta sesión.
minimal_address
boolean
predeterminado:"false"
Habilitar modo de recolección de dirección mínima. Cuando está habilitado, la compra solo recopila:
  • País: Siempre necesario para la determinación de impuestos
  • Código postal/ZIP: Solo en regiones donde es necesario para el cálculo de impuesto de ventas, IVA o GST
Esto reduce significativamente la fricción en la compra al eliminar campos de formulario innecesarios.
Habilitar dirección mínima para una finalización de compra más rápida. La recolección de dirección completa sigue disponible para empresas que requieren detalles completos de facturación.
customization
object
Personalizar la apariencia y el comportamiento de la interfaz de compra.
feature_flags
object
Configura características y comportamientos específicos para la sesión de compra.
custom_fields
array
Recolectar información adicional de clientes durante la compra con campos de formulario personalizados. Puedes definir hasta 5 campos personalizados por sesión de compra. Las respuestas de los clientes se incluyen en las cargas útiles de los webhooks y están disponibles a través de la API.
Las respuestas del cliente a campos personalizados están incluidas en:
  • Webhooks: payment.succeeded, subscription.active y otras cargas útiles de eventos relevantes contienen el array custom_field_responses
  • Respuestas API: Los objetos de pago y suscripción incluyen custom_field_responses
subscription_data
object
Configuración adicional para sesiones de compra que contienen productos de suscripción.

Ejemplos de Uso

Aquí hay 10 ejemplos completos que muestran diferentes configuraciones de sesión de compra para varios escenarios de negocio:

1. Compra Simple de Producto Único

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. Carrito de Múltiples Productos

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. Suscripción con Período de Prueba

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. Compra Preconfirmada

Cuando confirm está configurado en true, el cliente será llevado directamente a la página de compra, omitiendo cualquier paso de confirmación.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. Compra con Sobrescritura de Moneda

La sobrescritura billing_currency solo tiene efecto cuando la moneda adaptativa está habilitada en la configuración de tu cuenta. Si la moneda adaptativa está deshabilitada, este parámetro no tendrá efecto.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. Métodos de Pago Guardados para Clientes Recurrentes

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. Compras B2B con Recolección de ID Tributario

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

8. Compra con Tema Oscuro y Códigos de Descuento Acumulativos

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['BLACKFRIDAY2024'],
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

9. Métodos de Pago Regionales (UPI para India)

Para información detallada sobre la configuración y prueba de UPI, consulta la página de Métodos de Pago en India.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. Compra BNPL (Comprar Ahora Pagar Después)

Para información detallada sobre la configuración y prueba de BNPL, consulta la página de Comprar Ahora Pagar Después (BNPL).
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

11. Usar Métodos de Pago Existentes para Compra Instantánea

Utiliza un método de pago guardado del cliente para crear una sesión de compra que se procese inmediatamente, omitiendo la recolección del método de pago:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});
Cuando uses payment_method_id, confirm debe estar configurado en true y debe proporcionarse un customer_id existente. El método de pago será validado para elegibilidad con la moneda del pago.
El método de pago debe pertenecer al cliente y ser compatible con la moneda del pago. Esto permite compras con un solo clic para clientes recurrentes.

12. Enlaces Cortos para URLs de Pago más Limpias

Genera enlaces de pago acortados y compartibles con slugs personalizados:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123
Los enlaces cortos son perfectos para compartir por SMS, correo electrónico o redes sociales. Son más fáciles de recordar y generan más confianza que las URLs largas.

13. Omitir Página de Éxito de Pago con Redirección Inmediata

Redirige a los clientes inmediatamente tras la finalización del pago, omitiendo la página de éxito predeterminada:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});
Usa redirect_immediately: true cuando tengas una página de éxito personalizada que ofrezca una mejor experiencia de usuario que la página de éxito de pago predeterminada. Esto es especialmente útil para aplicaciones móviles y flujos de compra integrados.
Cuando redirect_immediately está habilitado, los clientes son redirigidos a tu return_url inmediatamente tras la finalización del pago, omitiendo por completo la página de éxito predeterminada.

14. Forzar un Idioma

Forzar la interfaz de compra a mostrarse en un idioma específico, sobrescribiendo la detección de idioma del navegador del cliente:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});
Usa force_language cuando conozcas el idioma preferido de tu cliente (por ejemplo, de la configuración de su cuenta) o cuando apuntas a mercados regionales específicos.
Idiomas soportados: Árabe (ar), Catalán (ca), Chino (zh), Holandés (nl), Inglés (en), Francés (fr), Alemán (de), Hebreo (he), Indonesio (id), Italiano (it), Japonés (ja), Coreano (ko), Malayo (ms), Polaco (pl), Portugués (pt), Rumano (ro), Ruso (ru), Español (es), Sueco (sv), Tailandés (th), Turco (tr)

15. Recolección de Campos Personalizados

Recopila información adicional de los clientes durante la compra usando campos personalizados:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});
Las respuestas a campos personalizados se incluyen automáticamente en las cargas útiles de webhook (payment.succeeded, subscription.active, etc.) y pueden ser recuperadas a través de la API. Úsalas para enriquecer tu CRM, activar flujos de incorporación o personalizar la experiencia del cliente.
Tipos de campo disponibles: text, number, email, url, date, dropdown, boolean

Previsualización de Sesiones de Compra

Antes de crear una sesión de compra, puedes previsualizar el desglose de precios incluyendo impuestos, descuentos y totales. Esto es útil para mostrar precios precisos a los clientes antes de que procedan a la compra.
const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'prod_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

console.log('Subtotal:', preview.subtotal);
console.log('Tax:', preview.tax);
console.log('Discount:', preview.discount);
console.log('Total:', preview.total);

Preview API Reference

Ver la documentación completa del endpoint de previsualización.

Transición de Enlaces Dinámicos a Sesiones de Compra

Diferencias Clave

Anteriormente, al crear un enlace de pago con Enlaces Dinámicos, era necesario proporcionar la dirección de facturación completa del cliente. Con Sesiones de Compra, esto ya no es necesario. Simplemente puedes pasar la información que tengas, y nosotros nos encargaremos del resto. Por ejemplo:
  • Si solo conoces el país de facturación del cliente, solo proporciona eso.
  • El flujo de compra recogerá automáticamente los detalles que falten antes de mover al cliente a la página de pago.
  • Por otro lado, si ya tienes toda la información requerida y deseas saltar directamente a la página de pago, puedes pasar el conjunto completo de datos e incluir confirm=true en el cuerpo de tu solicitud.

Proceso de Migración

La migración de Enlaces Dinámicos a Sesiones de Compra es sencilla:
1

Update your integration

Actualiza tu integración para usar el nuevo método de API o SDK.
2

Adjust request payload

Ajusta la carga útil de la solicitud según el formato de Sesiones de Compra.
3

That's it!

Sí. No se necesitan pasos de manejo o migración especiales adicionales de tu parte.

Referencia de API Relacionada

Create Checkout Session

Referencia completa de API para crear sesiones de compra con todos los parámetros disponibles y opciones

Preview Checkout Session

Referencia de API para previsualizar precios, impuestos y totales antes de crear una sesión
Last modified on May 26, 2026