Checkout Sessions - Dodo Payments Documentation

Quick Start

Create your first checkout session in under 5 minutes

API Reference

Full API documentation and interactive testing

Preview Endpoint

Calculate pricing and taxes before creating a session

Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when confirm: true.

Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

Prerequisites

You need:

An active Dodo Payments merchant account
API credentials from Developer → API Keys in the dashboard
At least one product created in Products

Creating Your First Checkout Session

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

async function createCheckoutSession() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      {
        product_id: 'pdt_123',
        quantity: 1
      }
    ],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
      phone_number: '+1234567890'
    },
    billing_address: {
      street: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      zipcode: '94102'
    },
    return_url: 'https://yoursite.com/checkout/success'
  });

  console.log('Checkout URL:', session.checkout_url);
  return session;
}

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

def create_checkout_session():
    session = client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": "pdt_123",
                "quantity": 1
            }
        ],
        customer={
            "email": "customer@example.com",
            "name": "John Doe",
            "phone_number": "+1234567890"
        },
        billing_address={
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "zipcode": "94102"
        },
        return_url="https://yoursite.com/checkout/success"
    )

    print(f"Checkout URL: {session.checkout_url}")
    return session

curl -X POST https://test.dodopayments.com/checkouts \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe",
      "phone_number": "+1234567890"
    },
    "billing_address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zipcode": "94102"
    },
    "return_url": "https://yoursite.com/checkout/success"
  }'

API Response

All methods return:

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

Only session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead. When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.

Redirect Your Customer

Extract the checkout URL

Get checkout_url from the API response.

Redirect to checkout

Send your customer to the URL:

window.location.href = session.checkout_url;

Alternatively, open in a new window:

window.open(session.checkout_url, '_blank');

Handle the return

After payment, customers are redirected to your return_url with query parameters:

Parameter	Type	Condition
`payment_id`	string	Always present for one-time payments
`subscription_id`	string	Always present for subscriptions
`status`	string	Always present
`license_key`	string	Present if the product has license keys enabled. Comma-separated if multiple keys
`email`	string	Present if the customer has an email on record

Example redirect:

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

Comprobar el estado de la sesión

Para comprobar el estado de una sesión, llama a Obtener sesión de Checkout (GET /checkouts/{id}). La respuesta contiene id, created_at, customer_email y customer_name de la sesión, además de payment_id y payment_status. Ambos campos de pago son null mientras el cliente sigue introduciendo sus datos. Después de que el cliente envíe el pago, payment_status contiene el estado del pago, como succeeded, failed o processing. Usa webhooks como fuente de verdad para la gestión de pedidos.

Cuerpo de la solicitud

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 dashboard.Puedes combinar productos de pago único con un producto de suscripción en la misma sesión. Un carrito también puede contener dos o más productos de suscripción, pero entonces no puede contener productos de pago único. Consulta Carrito con varias suscripciones. Un carrito puede contener como máximo 20 productos.

Mostrar Product Cart Item Properties

string

requerido

Identificador único del producto de tu dashboard.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 asociarán al producto. Solo es válida para productos de suscripción.

Mostrar Addon Item Properties

string

requerido

Identificador único del complemento.

integer

requerido

Cantidad del complemento.

integer

Importe que paga el cliente si pay-what-you-want está habilitado en el producto. Se representa en la denominación mínima de la moneda (por ejemplo, centavos para USD). Por ejemplo, 100 = $1.00.Se ignora si pay-what-you-want está deshabilitado.

array

Anulaciones por sesión para las asignaciones de créditos ya asociadas a este producto. Úsalo para conceder una cantidad diferente de créditos en esta sesión concreta sin crear un producto independiente.Cada credit_entitlement_id debe estar asociado previamente al producto. Este campo solo anula credits_amount, que se concede cuando se completa esta sesión; la configuración de asignaciones de créditos del producto (expiración, acumulación, etc.) sigue aplicándose.

Mostrar Credit Entitlement Override Properties

string

requerido

ID de la asignación de créditos que se anulará. Debe estar asociada previamente al producto.

string

requerido

Número de créditos que se concederán para esta sesión de checkout, anulando 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 dashboard de Dodo Payments, en Products → View Details, o mediante la API List Products.

Campos opcionales

Customer Information

object

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

Attach Existing Customer
Create New Customer

Mostrar Existing Customer Properties

string

requerido

Identificador único de un cliente existente.

Mostrar New Customer Properties

string

requerido

Dirección de correo electrónico del cliente.

string

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

string

Número de teléfono del cliente en formato internacional. Es 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"

object

Información de la dirección de facturación para calcular correctamente los impuestos, prevenir el fraude y cumplir la normativa.Cuando confirm: true, todos los campos de la dirección de facturación se vuelven obligatorios, a menos que minimal_address sea true.

Mostrar Billing Address Properties

string

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

string

Nombre de la ciudad o municipio.Ejemplo: "San Francisco"

string

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

string

requerido

Código de país ISO de dos letras (ISO 3166-1 alpha-2). Siempre es obligatorio cuando se proporciona billing_address.Ejemplos: "US", "CA", "GB", "DE"

Country Code Reference

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

string

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

Payment Configuration

array

Controla los métodos de pago disponibles para los clientes durante el checkout. Esto ayuda a optimizar el proceso para mercados específicos o requisitos empresariales.Opciones habituales: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalConsulta la referencia de la API Create Checkout Session para ver la lista completa.

Incluye siempre credit y debit como opciones alternativas 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 másEjemplo: "USD" para dólares estadounidenses, "EUR" para eurosEste campo solo es efectivo cuando el Adaptive Currency está habilitado. Si el Adaptive Currency está deshabilitado, la API descarta este campo y la moneda proviene del precio del producto o del país de facturación.

boolean

predeterminado:"false"

Muestra métodos de pago guardados anteriormente para clientes recurrentes, mejorando la velocidad del checkout y la experiencia del usuario.

Session Management

string

URL a la que se redirige a los clientes después de completar el pago. Dodo Payments añade parámetros de consulta a tu URL durante la redirección (consulta la tabla de redirecciones anterior).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 claves de licencia o enviar una confirmación inmediatamente en tu página de retorno, sin necesidad de realizar otra llamada a la API.

string

URL a la que se redirige a los clientes cuando hacen clic en el botón de volver o cancelan 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.

boolean

predeterminado:"false"

Si es true, finaliza inmediatamente todos los datos de la sesión. La API genera un error si faltan datos obligatorios.Cuando confirm: true:

Todos los campos de la dirección de facturación se vuelven obligatorios (solo country y zipcode cuando minimal_address es true)
Se puede proporcionar payment_method_id para procesar el cargo de inmediato
La sesión caduca después de 15 minutos en lugar de 24 horas
Se requiere un customer_id existente si se proporciona payment_method_id

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 inicial, el segundo reduce el precio ya rebajado, y así sucesivamente), hasta un máximo de 20 códigos por sesión.Cuando Purchasing Power Parity está habilitado, el precio inicial es el importe ajustado por PPP, no el precio base.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

El campo singular discount_code que aparece a continuación está obsoleto, pero sigue siendo totalmente compatible. No se puede combinar con discount_codes en la misma solicitud.

string

obsoleto

Obsoleto: para nuevas integraciones, usa discount_codes. 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 predeterminado de 3DS del merchant para esta sesión.

boolean

predeterminado:"false"

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

País: siempre obligatorio para determinar los impuestos
Código postal: solo en regiones donde sea necesario para calcular el impuesto sobre las ventas, VAT o GST

Esto reduce significativamente la fricción del checkout al eliminar campos de formulario innecesarios.Con confirm: true, solo se requiere zipcode (además de country); los demás campos de la dirección de facturación siguen siendo opcionales.

string

Un método de pago guardado que pertenece al customer adjunto. Requiere confirm: true y un customer.customer_id existente. La elegibilidad del método de pago se valida con la moneda del pago. Cuando se establece, el cargo se procesa de inmediato y checkout_url se devuelve como null. Usa el payment_id devuelto en su lugar.

boolean

predeterminado:"false"

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

string

ID de la colección de productos para el flujo de checkout basado en colecciones. Al establecerlo, proporciona un array product_cart vacío. Los códigos de descuento no se pueden aplicar previamente durante la creación de la sesión. Consulta Colecciones de productos.

string

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

string

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

integer

Anula el límite mínimo de mandato a nivel del merchant (en paise de INR) para los e-mandatos de INR en tarjetas indias.El importe del mandato enviado al procesador es max(this_floor, actual_billing_amount), por lo que este es efectivamente el límite máximo de autorización visible para el customer cuando la facturación es inferior. Si no se establece, se aplica la configuración del merchant; si esta tampoco se establece, se aplica el valor predeterminado del sistema de ₹15,000.

UI Customization

object

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

Mostrar Customization Properties

string

Tema de la interfaz de checkout. Opciones: light, dark o system. Si no se proporciona, el checkout usa el tema configurado para tu negocio en el dashboard.

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

Fuerza 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 customer.Códigos de idioma compatibles: ar, ca, de, en, es, fr, he, id, it, ja, ka, ko, ms, nl, pl, pt, ro, ru, sv, th, tr, zhEjemplo: "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 alternativa del servidor a la opción themeConfig del cliente, 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 100 caracteres.

string

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

Feature Flags

object

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

Mostrar Feature Flags Properties

boolean

predeterminado:"true"

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

boolean

predeterminado:"true"

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

boolean

predeterminado:"false"

Permite que los customers añadan o eliminen addons 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 customers durante el checkout.

boolean

predeterminado:"false"

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

boolean

predeterminado:"false"

Requiere que el customer introduzca el nombre de la tarjeta para pagar con tarjeta. Otros métodos de pago ignoran este flag.

boolean

predeterminado:"true"

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

boolean

predeterminado:"false"

Requiere que el customer proporcione un Tax ID (número GST en India, número VAT en la UE) antes de poder completar el checkout.Cuando está habilitado, Comprar como empresa se selecciona previamente y queda bloqueado en la página de checkout, y tanto Nombre de la empresa como Número de Tax ID se vuelven obligatorios. Consulta Pagos B2B para conocer el comportamiento completo del checkout.allow_tax_id también debe ser true. De lo contrario, la solicitud se rechaza con un 400 y el mensaje feature_flags.require_tax_id: cannot be true when allow_tax_id is false. Con confirm: true, la solicitud debe incluir un tax_id que no esté en blanco; de lo contrario, se rechaza con un 422.

boolean

predeterminado:"false"

Fuerza la creación de un nuevo registro de customer en lugar de actualizar los existentes.

boolean

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

boolean

Permite que los customers editen su nombre durante el checkout.

boolean

Permite que los customers editen la dirección durante el checkout.

boolean

Permite que los customers editen la ciudad durante el checkout.

boolean

Permite que los customers editen el estado o provincia durante el checkout.

boolean

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

boolean

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

boolean

Permite que los customers introduzcan o editen su Tax ID durante el checkout.

boolean

predeterminado:"false"

Permite que el customer proporcione o edite el nombre de la empresa asociado al Tax ID. Funciona independientemente de allow_customer_editing_tax_id: cualquiera de los dos flags (o allow_tax_id) es suficiente para permitir que el customer anule el nombre de empresa de la sesión. Normalmente se establece junto con allow_customer_editing_tax_id.

boolean

predeterminado:"false"

Omite la página de éxito de pago predeterminada y redirige inmediatamente a los customers a tu return_url después de completar el pago.Usa esta opción 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.

boolean

predeterminado:"false"

Si es true, la sesión utiliza el flujo de checkout de una sola página: la página inicializa el pago al cargarse y lo confirma en el mismo lugar, sin una página de pago independiente.

Custom Fields

array

Recopila información adicional de los customers durante el checkout mediante campos de formulario personalizados. Puedes definir hasta 5 campos personalizados por sesión de checkout. Las respuestas de los customers se incluyen en los payloads de webhook y están disponibles mediante la API.

Mostrar Custom Field Properties

string

requerido

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

string

requerido

Etiqueta que se muestra al customer 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 entrada.Tipos disponibles: text, number, email, url, date, dropdown, boolean

boolean

predeterminado:"false"

Indica si este campo debe completarse antes de poder 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 otros tipos.Ejemplo: ["Google", "Twitter", "Friend referral", "Other"]

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

Webhooks: payment.succeeded, subscription.active y otros payloads de eventos relevantes contienen el array 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 Properties

integer

Número de días del período de prueba antes del primer cargo. Debe estar entre 0 y 10000 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 Properties

boolean

requerido

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

integer

Precio del producto para el cargo inicial al customer. Si no se especifica, se utiliza el precio almacenado del producto.Formato: Se representa en la denominación mínima de la moneda (por ejemplo, centavos para USD). Por ejemplo, 100 = $1.00.

string

Moneda opcional del precio del producto. Si no se especifica, se utiliza de forma predeterminada 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 utiliza 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 el pricing adaptativo no está habilitado.

Ejemplos de uso

Checkout simple 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'
});

Carrito con varios productos

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

Carrito con varias suscripciones

Para vender varios productos de suscripción en un solo checkout, añade dos o más productos de suscripción a product_cart. El customer paga una vez y Dodo Payments crea un pago, una factura y una suscripción por cada producto. Cada suscripción tiene su propio ciclo de facturación y se renueva por separado, por lo que un producto mensual y uno anual pueden compartir un carrito.

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

Un carrito con varias suscripciones tiene estos límites:

No puede contener productos de pago único. La API rechaza la solicitud con un 422.
Puede contener como máximo 20 productos de suscripción.
No puede incluir el mismo producto dos veces. Para vender más de una unidad de un producto, establece quantity.
No puede utilizar facturación on-demand (subscription_data.on_demand).
Un código de descuento aplicado al carrito cuenta como un canje.

subscription_data.trial_period_days se aplica a cada suscripción del carrito. Sin él, cada suscripción utiliza la prueba configurada en su propio producto. Si no lo estableces y Prevent Trial Misuse está activado, un producto que el customer ya probó comienza sin período de prueba. El pago resultante tiene is_multi_subscription: true y enumera cada suscripción que inicia en subscription_ids. Su subscription_id es null, porque ninguna suscripción individual es propietaria del pago. El webhook payment.succeeded contiene los mismos campos. Lee is_multi_subscription para encontrar el tipo de pago, no la longitud de subscription_ids. Después de que el pago se realiza correctamente, recibes un evento payment.succeeded para el carrito y un evento subscription.active para cada suscripción. A partir de entonces, cada suscripción se renueva, cambia de plan y se cancela por separado, con su propia factura para cada renovación. Todas las suscripciones de un carrito comparten el método de pago que el customer utilizó durante el checkout. Cuando actualizas el método de pago de una de ellas, Dodo Payments mueve el nuevo método de pago a cada suscripción del mismo carrito que tenga la misma moneda de liquidación y moneda de facturación y sea active, on_hold, past_due o paused. Todas las suscripciones de un carrito comienzan con la misma moneda de liquidación y moneda de facturación, incluso cuando sus productos tienen monedas de precio diferentes. Un cambio posterior, como un cambio de plan, puede trasladar una suscripción a otra moneda de liquidación o de facturación. Esa suscripción conserva su método de pago anterior, por lo que debes actualizarlo por separado. Para una suscripción on_hold, la actualización solo reintenta la factura impagada de esa suscripción.

Suscripción con período de prueba

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

Checkout preconfirmado

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  billing_address: {
    street: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  confirm: true,
  return_url: 'https://yoursite.com/success'
});

Checkout con anulación de moneda

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

Métodos de pago guardados para customers recurrentes

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  show_saved_payment_methods: true,
  return_url: 'https://yoursite.com/success'
});

Checkout B2B con recopilación de Tax ID

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_enterprise_plan',
      quantity: 1
    }
  ],
  customer: {
    email: 'procurement@company.com',
    name: 'Jane Smith'
  },
  billing_address: {
    street: '456 Business Ave',
    city: 'London',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  feature_flags: {
    require_tax_id: true
  },
  return_url: 'https://yoursite.com/success'
});

Checkout con tema oscuro y códigos de descuento apilados

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

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_123',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  billing_address: {
    street: '123 Main St',
    city: 'Bangalore',
    state: 'KA',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  allowed_payment_method_types: ['upi_intent', 'credit', 'debit'],
  return_url: 'https://yoursite.com/success'
});

Checkout con BNPL (Buy Now Pay Later)

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_123',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  allowed_payment_method_types: ['klarna', 'affirm', 'afterpay_clearpay', 'credit', 'debit'],
  return_url: 'https://yoursite.com/success'
});

Checkout instantáneo con un método de pago existente

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  payment_method_id: 'pm_existing_payment_method_id',
  confirm: true,
  return_url: 'https://yoursite.com/success'
});

Enlaces cortos para URL de pago más limpias

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

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

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

Forzar un idioma

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

Recopilar campos personalizados

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      options: ['Google', 'Twitter', 'Friend referral', 'Other'],
      required: true
    }
  ],
  return_url: 'https://yoursite.com/success'
});

Previsualizar sesiones de checkout

Usa el endpoint Preview Checkout Session para calcular precios, impuestos y totales antes de crear una sesión. Esto resulta útil para mostrar información de precios precisa en tu sitio.

El current_breakup.subtotal previsualizado ya refleja Purchasing Power Parity y Charm Pricing cuando se aplican al producto.

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 en relación con el momento actual: now + trial period cuando se aplica una prueba; de lo contrario, now + one payment frequency. El campo se omite en los carritos que solo contienen productos 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) y 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 para una prueba de pago y es null para una prueba gratuita o cuando no hay prueba. Usa current_breakup para obtener el total gravado que realmente se debe pagar hoy.

Para un carrito con varias suscripciones, la respuesta también devuelve un array subscriptions con una entrada por suscripción: product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days y next_billing_date. El next_billing_date de nivel superior es la fecha más temprana del carrito, y trial_period_days e trial_amount de nivel superior son null. Lee los importes de subscriptions y current_breakup. recurring_breakup suma los importes de renovación de todas las suscripciones, incluso cuando se renuevan en fechas diferentes, por lo que debes leer cada renovación de subscriptions.

Node.js SDK
Python SDK
REST API

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}")

curl -X POST https://test.dodopayments.com/checkouts/preview \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "billing_address": {
      "country": "US",
      "state": "CA",
      "zipcode": "94102"
    },
    "discount_codes": ["SAVE20"]
  }'

Migrar desde Dynamic Links

Si utilizas Dynamic Links, Checkout Sessions ofrecen más flexibilidad. Con Dynamic Links, tenías que proporcionar la dirección de facturación completa del customer. Con Checkout Sessions, puedes enviar la información que tengas y el flujo de checkout recopila el resto. Por ejemplo:

Proporciona solo el país de facturación del customer y el checkout recopila los datos restantes.
O proporciona toda la información y establece confirm: true para pasar directamente a la página de pago.

La migración es sencilla: actualiza tu integración para utilizar la API de Checkout Sessions o el método del SDK, ajusta el payload de la solicitud para que coincida con el formato de Checkout Sessions y listo. No se requiere ningún tratamiento adicional.

Recursos relacionados

Overlay Checkout

Abre el checkout como una ventana modal superpuesta en tu página

Inline Checkout

Integra el checkout directamente en tu página

Mobile Integration

Integra el checkout en aplicaciones móviles nativas

Webhooks

Escucha eventos de pago y suscripción

Payment Methods

Métodos de pago compatibles por región

Subscriptions

Facturación recurrente y gestión de suscripciones

Quick Start

API Reference

Preview Endpoint

​Prerequisites

​Creating Your First Checkout Session

​API Response

​Redirect Your Customer

​Comprobar el estado de la sesión

​Cuerpo de la solicitud

​Campos obligatorios

​Campos opcionales

Country Code Reference

​Ejemplos de uso

​Checkout simple de un solo producto

​Carrito con varios productos

​Carrito con varias suscripciones

​Suscripción con período de prueba

​Checkout preconfirmado

​Checkout con anulación de moneda

​Métodos de pago guardados para customers recurrentes

​Checkout B2B con recopilación de Tax ID

​Checkout con tema oscuro y códigos de descuento apilados

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

​Checkout con BNPL (Buy Now Pay Later)

​Checkout instantáneo con un método de pago existente

​Enlaces cortos para URL de pago más limpias

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

​Forzar un idioma

​Recopilar campos personalizados

​Previsualizar sesiones de checkout

​Migrar desde Dynamic Links

​Recursos relacionados

Overlay Checkout

Inline Checkout

Mobile Integration

Webhooks

Payment Methods

Subscriptions

Prerequisites

Creating Your First Checkout Session

API Response

Redirect Your Customer

Comprobar el estado de la sesión

Cuerpo de la solicitud

Campos obligatorios

Campos opcionales

Ejemplos de uso

Checkout simple de un solo producto

Carrito con varios productos

Carrito con varias suscripciones

Suscripción con período de prueba

Checkout preconfirmado

Checkout con anulación de moneda

Métodos de pago guardados para customers recurrentes

Checkout B2B con recopilación de Tax ID

Checkout con tema oscuro y códigos de descuento apilados

Métodos de pago regionales (UPI para India)

Checkout con BNPL (Buy Now Pay Later)

Checkout instantáneo con un método de pago existente

Enlaces cortos para URL de pago más limpias

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

Forzar un idioma

Recopilar campos personalizados

Previsualizar sesiones de checkout

Migrar desde Dynamic Links

Recursos relacionados