Checkout Sessions

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.

Single-Use Links: The checkout_url returned by the API is not reusable and expires within 24 hours (or 15 minutes when confirm=true). It is intended for a single customer to complete one payment. Generate a fresh checkout session for each customer and each payment attempt rather than sharing or reusing a link.

Prerequisites

Dodo Payments Account

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

API Credentials

Generate your API credentials from the Dodo Payments dashboard:

Products Setup

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

Creating Your First Checkout Session

Node.js SDK
Python SDK
REST API

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: 'pdt_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' });
  }
});

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.create(
            # Products to sell - use IDs from your Dodo Payments dashboard
            product_cart=[
                {
                    "product_id": "pdt_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout 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
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // Products to sell - use IDs from your Dodo Payments dashboard
        product_cart: [
          {
            product_id: 'pdt_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout 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'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // 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: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

API Response

All methods above return the same response structure:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Solo se garantiza que esté presente session_id. En dos casos se devuelven campos adicionales o menos campos:

Se proporcionó payment_method_id: el cargo se procesa de inmediato y checkout_url es null. Usa en su lugar el payment_id devuelto.
confirm: true creó el pago al crear la sesión: la respuesta también incluye payment_id, client_secret e publishable_key para usarlos con el SDK de checkout de Dodo Payments.

El checkout_url generado es de un solo uso y caduca en un plazo de 24 horas. No lo guardes en caché ni lo reutilices entre clientes o intentos de pago; crea una nueva sesión de checkout cada vez que necesites un enlace nuevo.

Get the checkout URL

Extrae checkout_url de la respuesta de la API.

Redirect your customer

Dirige al cliente a la URL de checkout para completar su compra.

// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');

Opciones de integración alternativas: En lugar de redirigir, puedes insertar el checkout directamente en tu página mediante Overlay Checkout (superposición modal) o Inline Checkout (completamente integrado). En una aplicación móvil nativa, proporciona la misma URL a los SDK de Mobile Checkout para Android, iOS, React Native o Flutter. Todos consumen la misma URL de sesión de checkout.

Handle the return

Después del pago, los clientes son redirigidos a tu return_url con parámetros de consulta que incluyen el ID del pago o la suscripción, el estado, el correo electrónico del cliente y cualquier clave de licencia. Consulta la documentación de parámetros de return_url para ver la lista completa.

Cuerpo de la solicitud

Required Fields

Campos esenciales necesarios para cada sesión de checkout

Optional Fields

Configuración adicional para personalizar tu experiencia de checkout

Campos obligatorios

array

requerido

Matriz de productos que se incluirán en la sesión de checkout. Cada producto debe tener un product_id válido de tu panel de Dodo Payments.

Checkout mixto: Puedes combinar productos de pago único y productos de suscripción en la misma sesión de checkout. Esto permite casos de uso como tarifas de configuración con suscripciones, paquetes de hardware con SaaS y mucho más.

Mostrar Product Cart Item Properties

string

requerido

El identificador único del producto de tu panel de Dodo Payments.Ejemplo: "pdt_123abc456def"

integer

requerido

Cantidad del producto.Ejemplo: 1 para un solo artículo, 3 para varias unidades

array

Matriz de complementos que se adjuntarán al producto. Solo es válido si el producto es una suscripción.

Mostrar Addon item properties

string

requerido

integer

requerido

integer

Importe que paga el cliente si pay_what_you_want está habilitado. Si está deshabilitado, este campo se ignorará.Formato: Se representa en la denominación más pequeña de la moneda (por ejemplo, centavos para USD). Para cobrar $1.00, pasa 100.

array

Anulaciones por sesión de checkout para los derechos de crédito ya asociados a este producto. Úsalo para conceder una cantidad diferente de créditos en esta sesión; por ejemplo, un paquete promocional que concede 1.000 créditos de API en lugar de los 500 predeterminados del producto, sin crear un producto independiente.

Cada credit_entitlement_id ya debe estar asociado al producto. Este campo solo anula el credits_amount concedido cuando se completa esta sesión; la configuración de derechos de crédito a nivel de producto (caducidad, renovación, etc.) sigue aplicándose.

Mostrar Credit entitlement override properties

string

requerido

ID del derecho de crédito que se anulará. Ya debe estar asociado al producto.

string

requerido

Cantidad de créditos que se concederán para esta sesión de checkout, anulando el credits_amount a nivel de producto. Debe ser mayor que cero.

Encuentra los ID de tus productos: Puedes encontrar los ID de producto en tu panel de Dodo Payments, en Products → View Details, o mediante la API List Products.

Campos opcionales

Configura estos campos para personalizar la experiencia de checkout y añadir lógica empresarial a tu flujo de pago.

Customer Information

object

Información del cliente. Puedes asociar un cliente existente mediante su ID o crear un nuevo registro durante el checkout.

Attach Existing Customer
New Customer

Asocia un cliente existente a la sesión de checkout mediante su ID.

Mostrar Existing Customer Properties

string

requerido

El identificador único de un cliente existente. Úsalo para asociar la sesión de checkout a un cliente existente en lugar de crear uno nuevo.

Crea un nuevo registro de cliente durante el checkout.

Mostrar New Customer Properties

string

requerido

Dirección de correo electrónico del cliente. Obligatoria al crear un cliente nuevo.

string

Nombre completo del cliente tal como debe aparecer en recibos y facturas.Ejemplo: "John Doe" o "Jane Smith"

string

Número de teléfono del cliente en formato internacional. Obligatorio para algunos métodos de pago y para la prevención del fraude.Formato: Incluye el código de país; por ejemplo, "+1234567890" para números de EE. UU.

object

Información de la dirección de facturación para calcular correctamente los impuestos, prevenir el fraude y cumplir la normativa.

Cuando confirm se establece en true, todos los campos de la dirección de facturación son obligatorios para crear correctamente la sesión.

Mostrar Billing address object properties

string

Dirección completa, incluidos el número y el nombre de la calle y, si corresponde, el número del apartamento o unidad.Ejemplo: "123 Main St, Apt 4B" o "456 Oak Avenue"

string

Nombre de la ciudad o municipio.Ejemplo: "San Francisco", "New York", "London"

string

Nombre del estado, provincia o región. Usa nombres completos o abreviaturas estándar.Ejemplo: "California" o "CA", "Ontario" o "ON"

string

requerido

Código de país ISO de dos letras (ISO 3166-1 alpha-2). Este campo siempre es obligatorio cuando se proporciona billing_address.Ejemplos: "US" (Estados Unidos), "CA" (Canadá), "GB" (Reino Unido), "DE" (Alemania)

Country Code Reference

Consulta la lista completa de países compatibles y sus códigos ISO

string

Código postal, código ZIP o equivalente según los requisitos del país.Ejemplos: "94102" (EE. UU.), "M5V 3A8" (Canadá), "SW1A 1AA" (Reino Unido)

Payment Configuration

array

Controla qué métodos de pago están disponibles para los clientes durante el checkout. Esto ayuda a optimizarlo para mercados específicos o requisitos empresariales.Opciones comunes: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, paypal. Este no es el conjunto completo; consulta la referencia de la API Create Checkout Session para ver todos los valores aceptados.

Importante: Incluye siempre credit y debit como opciones de reserva para evitar errores de checkout cuando los métodos de pago preferidos no estén disponibles.

Ejemplo:

["apple_pay", "google_pay", "credit", "debit"]

string

Anula la selección de moneda predeterminada con una moneda de facturación fija. Usa códigos de moneda ISO 4217.Monedas compatibles: USD, EUR, GBP, CAD, AUD, INR y otrasEjemplo: "USD" para dólares estadounidenses, "EUR" para euros

Este campo solo tiene efecto cuando los precios adaptativos están habilitados. Si están deshabilitados, se usará la moneda predeterminada del producto.

boolean

predeterminado:"false"

Muestra los métodos de pago guardados anteriormente a los clientes recurrentes para mejorar la velocidad y la experiencia del checkout.

Session Management

string

URL a la que se redirigirá a los clientes después de completar el pago. Dodo Payments añade los siguientes parámetros de consulta a tu URL durante la redirección:

Parámetro	Tipo	Condición
`payment_id`	`string`	Siempre presente para pagos únicos
`subscription_id`	`string`	Siempre presente para pagos de suscripción
`status`	`string`	Siempre presente
`license_key`	`string`	Presente si el producto tiene habilitadas las claves de licencia. Separado por comas si hay varias claves
`email`	`string`	Presente si el cliente tiene un correo electrónico registrado

URL de redirección de ejemplo:

# 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

Usa los parámetros de consulta license_key y email para mostrar las claves de licencia o enviar inmediatamente una confirmación en tu página de retorno, sin necesidad de realizar otra llamada a la API.

string

URL a la que se redirigirá a los clientes cuando hagan clic en el botón de volver o cancelen la sesión de checkout. Si no se proporciona, el botón de volver no se mostrará.

Establece un cancel_url para ofrecer a los clientes una forma clara de volver a tu sitio sin completar la compra. Esto mejora la experiencia de checkout y reduce la fricción.

boolean

predeterminado:"false"

Si es true, finaliza inmediatamente todos los detalles de la sesión. La API generará un error si faltan datos obligatorios.

array

Aplica uno o más códigos de descuento acumulables a la sesión de checkout. Los códigos se aplican en el orden de la matriz (el primero 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 que aparece a continuación está obsoleto, pero sigue siendo totalmente compatible; las integraciones existentes continúan funcionando sin cambios. No se puede combinar con discount_codes en la misma solicitud. Migra a discount_codes cuando te resulte conveniente para aprovechar la acumulación.

string

obsoleto

Obsoleto; usa discount_codes para las integraciones nuevas. Este campo sigue funcionando por compatibilidad con versiones anteriores, pero no se puede combinar con discount_codes en la misma solicitud.

object

Pares clave-valor personalizados para almacenar información adicional sobre la sesión.

boolean

Anula el comportamiento de 3DS predeterminado del merchant para esta sesión.

boolean

predeterminado:"false"

Habilita el modo de recopilación mínima de direcciones. Cuando está habilitado, el checkout solo recopila:

País: Siempre obligatorio para determinar los impuestos
Código ZIP o postal: Solo en regiones donde sea necesario para calcular el impuesto sobre las ventas, el IVA o el GST

Esto reduce considerablemente la fricción del checkout al eliminar campos de formulario innecesarios.

Habilita la dirección mínima para completar el checkout más rápido. La recopilación de la dirección completa sigue disponible para las empresas que necesitan todos los datos de facturación.

string

Método de pago guardado perteneciente al cliente asociado. Requiere confirm: true y un customer.customer_id existente. Cuando se establece, el cargo se procesa de inmediato y checkout_url se devuelve como null; usa en su lugar el payment_id devuelto.

boolean

predeterminado:"false"

Si es true, devuelve una URL de checkout abreviada en lugar de la URL de sesión completa.

string

ID de la colección de productos para el flujo de checkout basado en colecciones.

string

ID fiscal del cliente (por ejemplo, un número de IVA). Requiere billing_address con un country.

string

Nombre comercial o legal opcional asociado al ID fiscal. Cuando se proporciona junto con un tax_id válido, se muestra en la factura en lugar del nombre personal del cliente.

integer

Anula el límite mínimo del mandato a nivel de merchant (en paise de INR) para los mandatos electrónicos en INR de tarjetas indias.

UI Customization & Features

object

Personaliza la apariencia y el comportamiento de la interfaz de checkout.

Mostrar Customization object properties

string

predeterminado:"system"

Tema de la interfaz de checkout. Opciones: light, dark o system.

boolean

predeterminado:"true"

Muestra la sección de detalles del pedido en la interfaz de checkout.

boolean

predeterminado:"true"

Muestra la etiqueta “on-demand” para los productos aplicables.

string

Obliga a la interfaz de checkout a mostrarse en un idioma específico. De forma predeterminada, el checkout detecta automáticamente el idioma del navegador del cliente.Códigos de idioma compatibles: ar (árabe), ca (catalán), de (alemán), en (inglés), es (español), fr (francés), he (hebreo), id (indonesio), it (italiano), ja (japonés), ko (coreano), ms (malayo), nl (neerlandés), pl (polaco), pt (portugués), ro (rumano), ru (ruso), sv (sueco), th (tailandés), tr (turco), zh (chino)Ejemplo: "es" para español, "ja" para japonés

object

Configuración de tema personalizada con colores para los modos claro y oscuro, fuentes y estilos de botones. Esta es la sustitución del lado del servidor para la opción del lado del cliente themeConfig, que está obsoleta.

Mostrar Theme config properties

object

Configuración de colores del modo claro.

object

Configuración de colores del modo oscuro.

string

URL de la fuente principal. Debe ser una URL https:// válida.

string

URL de la fuente secundaria. Debe ser una URL https:// válida.

string

Tamaño de fuente para la interfaz de checkout. Opciones: xs, sm, md, lg, xl, 2xl.

string

Peso de fuente para la interfaz de checkout. Opciones: normal, medium, bold, extraBold.

string

Texto personalizado para el botón de pago (por ejemplo, "Complete Purchase" o "Subscribe Now"). Máximo de 100 caracteres.

string

Radio de borde para los elementos de la interfaz. Un número seguido de px, rem o em (por ejemplo, "4px", "0.5rem", "1em").

object

Configura funciones y comportamientos específicos para la sesión de checkout.

Mostrar Feature flags object properties

boolean

predeterminado:"true"

Permite que los clientes seleccionen su moneda preferida durante el checkout.

boolean

predeterminado:"true"

Muestra el campo de código de descuento en la interfaz de checkout.

boolean

predeterminado:"false"

Permite que los clientes añadan o eliminen complementos de un producto de suscripción durante el checkout. Solo se aplica a productos de suscripción.

boolean

predeterminado:"true"

Recopila los números de teléfono de los clientes durante el checkout.

boolean

predeterminado:"false"

Exige que el cliente proporcione un número de teléfono para completar el checkout. También requiere que allow_phone_number_collection sea true.

boolean

predeterminado:"true"

Permite que los clientes introduzcan números de identificación fiscal.

boolean

predeterminado:"false"

Obliga a crear un nuevo registro de cliente en lugar de actualizar los existentes.

boolean

Permite que los clientes editen su dirección de correo electrónico durante el checkout.

boolean

Permite que los clientes editen su nombre durante el checkout.

boolean

Permite que los clientes editen la dirección de la calle durante el checkout.

boolean

Permite que los clientes editen la ciudad durante el checkout.

boolean

Permite que los clientes editen el estado durante el checkout.

boolean

Permite que los clientes editen el país durante el checkout.

boolean

Permite que los clientes editen el código postal durante el checkout.

boolean

Permite que los clientes introduzcan o editen su ID fiscal durante el checkout.

boolean

predeterminado:"false"

Permite que el cliente proporcione o edite el nombre comercial asociado al ID fiscal. Funciona independientemente de allow_customer_editing_tax_id; cualquiera de los dos indicadores (o allow_tax_id) es suficiente. Normalmente se configura junto con allow_customer_editing_tax_id.

boolean

predeterminado:"false"

Omite la página de éxito de pago predeterminada y redirige inmediatamente a los clientes a tu return_url una vez completado el pago.

Úsalo cuando tengas una página de éxito personalizada que ofrezca una mejor experiencia de usuario, o para aplicaciones móviles y flujos de checkout integrados.

Custom Fields

array

Recopila información adicional de los clientes durante el checkout mediante campos de formulario personalizados. Puedes definir hasta 5 campos personalizados por sesión de checkout. Las respuestas de los clientes se incluyen en las cargas útiles de los webhooks y están disponibles mediante la API.

Mostrar Custom field object properties

string

requerido

Identificador único de este campo. Se utiliza como clave en las cargas útiles de los webhooks y en las respuestas de la API.Ejemplo: "company_name", "referral_source", "team_size"

string

requerido

Etiqueta que se muestra al cliente en el formulario de checkout.Ejemplo: "Company Name", "How did you hear about us?", "Team Size"

string

requerido

Tipo de campo que determina las reglas de validación de la entrada.Tipos disponibles:

text - Entrada de texto de una sola línea
number - Entrada numérica
email - Dirección de correo electrónico con validación
url - URL con validación
date - Selector de fecha
dropdown - Selección entre opciones predefinidas
boolean - Interruptor Sí/No

boolean

predeterminado:"false"

Indica si este campo debe completarse antes de que pueda finalizar el checkout.

string

Texto de marcador de posición que se muestra en el campo de entrada.

array

Lista de opciones para el tipo de campo dropdown. Obligatoria cuando field_type es dropdown; se ignora para los demás tipos.Ejemplo: ["Google", "Twitter", "Friend referral", "Other"]

Las respuestas de los clientes a los campos personalizados se incluyen en:

Webhooks: payment.succeeded, subscription.active y otras cargas útiles de eventos relevantes contienen la matriz custom_field_responses
Respuestas de la API: Los objetos de pago y suscripción incluyen custom_field_responses

Subscription Configuration

object

Configuración adicional para sesiones de checkout que contienen productos de suscripción.

Mostrar Subscription data object properties

integer

Número de días del periodo de prueba antes del primer cargo. Debe estar entre 0 y 10.000 días.No se puede establecer un importe de prueba de pago por sesión; configura trial_amount en el precio recurrente del producto. Consulta Pruebas de pago.

object

Configuración de suscripción on-demand para facturación basada en el uso o medida.

Mostrar On-demand object properties

boolean

requerido

Si se establece en true, no realiza ningún cargo y solo autoriza los datos del método de pago para su uso futuro.

integer

Precio del producto para el cargo inicial al cliente. Si no se especifica, se usará el precio almacenado del producto.Formato: Se representa en la denominación más pequeña de la moneda (por ejemplo, centavos para USD). Para cobrar $1.00, pasa 100.

string

Moneda opcional del precio del producto. Si no se especifica, se establece de forma predeterminada en la moneda del producto.

string

Anulación opcional de la descripción del producto para la facturación y las partidas. Si no se especifica, se usará la descripción almacenada del producto.

boolean

Indica si las tarifas de Adaptive Currency deben incluirse en el precio del producto (true) o añadirse aparte (false). Se ignora si los precios adaptativos no están habilitados.

Ejemplos de uso

Estos son 10 ejemplos completos que muestran diferentes configuraciones de sesiones de checkout para varios escenarios empresariales:

1. Checkout sencillo de un solo producto

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

2. Carrito con varios productos

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_laptop',
      quantity: 1
    },
    {
      product_id: 'pdt_mouse',
      quantity: 2
    },
    {
      product_id: 'pdt_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 periodo de prueba

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Checkout preconfirmado

Cuando confirm se establece en true, el cliente accederá directamente a la página de checkout, omitiendo los pasos de confirmación.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Checkout con anulación de moneda

La anulación de billing_currency solo tiene efecto cuando Adaptive Currency está habilitado en la configuración de tu cuenta. Si Adaptive Currency está deshabilitado, este parámetro no tendrá ningún efecto.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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: 'pdt_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. Checkout B2B con recopilación del ID fiscal

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Checkout con tema oscuro y códigos de descuento acumulables

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 obtener información detallada sobre la configuración y las pruebas de UPI, consulta la página Métodos de pago de India.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Checkout BNPL (compra ahora y paga después)

Para obtener información detallada sobre la configuración y las pruebas de BNPL, consulta la página Buy Now Pay Later (BNPL).

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Uso de métodos de pago existentes para checkout instantáneo

Usa el método de pago guardado de un cliente para crear una sesión de checkout que se procese de inmediato, omitiendo la recopilación del método de pago:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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'
});

Al usar payment_method_id, confirm debe establecerse en true y debe proporcionarse un customer_id existente. El método de pago se validará para comprobar su elegibilidad con la moneda del pago. Como el cargo se procesa de inmediato, checkout_url se devuelve como null; usa en su lugar el payment_id devuelto.

El método de pago debe pertenecer al cliente y ser compatible con la moneda del pago. Esto permite realizar compras con un solo clic para los clientes recurrentes.

12. Enlaces cortos para URL de pago más limpias

Genera enlaces de pago abreviados y fáciles de compartir con slugs personalizados:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 ideales para compartir por SMS, correo electrónico o redes sociales. Son más fáciles de recordar y generan más confianza en los clientes que las URL largas.

13. Omitir la página de éxito del pago con redirección inmediata

Redirige inmediatamente a los clientes una vez completado el pago, omitiendo la página de éxito predeterminada:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 predeterminada. Esto resulta especialmente útil para aplicaciones móviles y flujos de checkout integrados.

Cuando redirect_immediately está habilitado, los clientes son redirigidos a tu return_url inmediatamente después de completar el pago, omitiendo por completo la página de éxito predeterminada.

14. Forzar un idioma

Obliga al checkout a mostrarse en un idioma específico, anulando la detección del idioma del navegador del cliente:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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, a partir de la configuración de su cuenta) o cuando te dirijas a mercados regionales específicos.

Idiomas compatibles: árabe (ar), catalán (ca), chino (zh), neerlandé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. Recopilar campos personalizados

Recopila información adicional de los clientes durante el checkout mediante campos personalizados:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 de los campos personalizados se incluyen automáticamente en las cargas útiles de los webhooks (payment.succeeded, subscription.active, etc.) y se pueden recuperar mediante 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

Previsualizar sesiones de checkout

Antes de crear una sesión de checkout, puedes previsualizar el desglose de precios, incluidos impuestos, descuentos y totales. Esto resulta útil para mostrar precios precisos a los clientes antes de que procedan al checkout.

Cuando el carrito contiene un producto de suscripción, la respuesta de previsualización también devuelve un next_billing_date, una previsualización de la próxima fecha de facturación, para que puedas mostrarla antes de crear la suscripción. Se calcula con respecto al momento actual: now + trial period cuando se aplica una prueba; de lo contrario, now + one payment frequency. El campo se omite en carritos exclusivamente de pago único. Es una estimación basada en el momento de la previsualización; el next_billing_date autorizado se establece cuando se activa la suscripción.

La previsualización también devuelve trial_period_days (la duración efectiva de la prueba, gratuita o de pago) e trial_amount (el cargo de prueba por unidad después de los descuentos, en las unidades menores de la moneda del precio). trial_amount solo está presente en una prueba de pago y es null en una prueba gratuita o cuando no hay prueba. Usa current_breakup para consultar el total gravado que se debe pagar hoy.

Node.js SDK
Python SDK

const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'pdt_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

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

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

preview = client.checkout_sessions.preview(
    product_cart=[
        {"product_id": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

print(f"Subtotal: {preview.current_breakup.subtotal}")
print(f"Tax: {preview.current_breakup.tax}")
print(f"Discount: {preview.current_breakup.discount}")
print(f"Total: {preview.current_breakup.total_amount}")

# Present only when the cart contains a subscription product
print(f"Next billing date: {preview.next_billing_date}")

Preview API Reference

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

Pasar de Dynamic Links a Checkout Sessions

Diferencias clave

Anteriormente, al crear un enlace de pago con Dynamic Links, era obligatorio proporcionar la dirección de facturación completa del cliente. Con Checkout Sessions, esto ya no es necesario. Puedes transmitir simplemente la información que tengas y nosotros nos encargaremos del resto. Por ejemplo:

Si solo conoces el país de facturación del cliente, proporciona únicamente ese dato.
El flujo de checkout recopilará automáticamente los datos que falten antes de dirigir al cliente a la página de pago.
Por otro lado, si ya tienes toda la información necesaria y quieres ir directamente a la página de pago, puedes proporcionar el conjunto de datos completo e incluir confirm=true en el cuerpo de la solicitud.

Proceso de migración

Migrar de Dynamic Links a Checkout Sessions es sencillo:

Update your integration

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

Adjust request payload

Ajusta la carga útil de la solicitud según el formato de Checkout Sessions.

That's it!

Sí. No necesitas realizar ningún tratamiento adicional ni pasos especiales de migración.

Referencia de API relacionada

Create Checkout Session

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

Preview Checkout Session

Referencia de la API para previsualizar precios, impuestos y totales antes de crear una sesión

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

Prerequisites

Creating Your First Checkout Session

API Response

Cuerpo de la solicitud

Required Fields

Optional Fields

Campos obligatorios

Campos opcionales

Country Code Reference

Ejemplos de uso

1. Checkout sencillo de un solo producto

2. Carrito con varios productos

3. Suscripción con periodo de prueba

4. Checkout preconfirmado

5. Checkout con anulación de moneda

6. Métodos de pago guardados para clientes recurrentes

7. Checkout B2B con recopilación del ID fiscal

8. Checkout con tema oscuro y códigos de descuento acumulables

9. Métodos de pago regionales (UPI para India)

10. Checkout BNPL (compra ahora y paga después)

11. Uso de métodos de pago existentes para checkout instantáneo

12. Enlaces cortos para URL de pago más limpias

13. Omitir la página de éxito del pago con redirección inmediata

14. Forzar un idioma

15. Recopilar campos personalizados

Previsualizar sesiones de checkout

Preview API Reference

Pasar de Dynamic Links a Checkout Sessions

Diferencias clave

Proceso de migración

Referencia de API relacionada

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​Prerequisites

​Creating Your First Checkout Session

​API Response

​Cuerpo de la solicitud

Required Fields

Optional Fields

​Campos obligatorios

​Campos opcionales

Country Code Reference

​Ejemplos de uso

​1. Checkout sencillo de un solo producto

​2. Carrito con varios productos

​3. Suscripción con periodo de prueba

​4. Checkout preconfirmado

​5. Checkout con anulación de moneda

​6. Métodos de pago guardados para clientes recurrentes

​7. Checkout B2B con recopilación del ID fiscal

​8. Checkout con tema oscuro y códigos de descuento acumulables

​9. Métodos de pago regionales (UPI para India)

​10. Checkout BNPL (compra ahora y paga después)

​11. Uso de métodos de pago existentes para checkout instantáneo

​12. Enlaces cortos para URL de pago más limpias

​13. Omitir la página de éxito del pago con redirección inmediata

​14. Forzar un idioma

​15. Recopilar campos personalizados

​Previsualizar sesiones de checkout

Preview API Reference

​Pasar de Dynamic Links a Checkout Sessions

​Diferencias clave

​Proceso de migración

​Referencia de API relacionada

Create Checkout Session

Preview Checkout Session

Prerequisites

Creating Your First Checkout Session

API Response

Cuerpo de la solicitud

Campos obligatorios

Campos opcionales

Ejemplos de uso

1. Checkout sencillo de un solo producto

2. Carrito con varios productos

3. Suscripción con periodo de prueba

4. Checkout preconfirmado

5. Checkout con anulación de moneda

6. Métodos de pago guardados para clientes recurrentes

7. Checkout B2B con recopilación del ID fiscal

8. Checkout con tema oscuro y códigos de descuento acumulables

9. Métodos de pago regionales (UPI para India)

10. Checkout BNPL (compra ahora y paga después)

11. Uso de métodos de pago existentes para checkout instantáneo

12. Enlaces cortos para URL de pago más limpias

13. Omitir la página de éxito del pago con redirección inmediata

14. Forzar un idioma

15. Recopilar campos personalizados

Previsualizar sesiones de checkout

Pasar de Dynamic Links a Checkout Sessions

Diferencias clave

Proceso de migración

Referencia de API relacionada