Skip to main content

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

API Response

All methods return:
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

1

Extract the checkout URL

Get checkout_url from the API response.
2

Redirect to checkout

Send your customer to the URL:
Alternatively, open in a new window:
3

Handle the return

After payment, customers are redirected to your return_url with query parameters:Example redirect:
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 y productos de suscripción en la misma sesión.
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

object
Información del cliente. Puedes asociar un cliente existente mediante su ID o crear un nuevo registro de cliente durante el checkout.
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 pasan a ser obligatorios.
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:
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 tiene efecto cuando adaptive pricing está habilitado. Si adaptive pricing está deshabilitado, se usa la moneda predeterminada del producto.
boolean
predeterminado:"false"
Muestra métodos de pago guardados anteriormente para clientes recurrentes, mejorando la velocidad del checkout y la experiencia del usuario.
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:
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 pasan a ser obligatorios
  • Se puede proporcionar payment_method_id para procesar el cargo inmediatamente
  • 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.
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.
string
Método de pago guardado perteneciente al cliente asociado. Requiere confirm: true y un customer.customer_id existente. El método de pago se valida para comprobar su compatibilidad con la moneda del pago. Cuando se establece, el cargo se procesa inmediatamente y checkout_url se devuelve como null. Usa en su lugar el payment_id devuelto.
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 una matriz product_cart vacía. Los códigos de descuento no se pueden aplicar previamente durante la creación de la sesión. Consulta Product Collections.
string
ID fiscal del cliente (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, aparece 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 e-mandates de INR en tarjetas de India.El importe del mandato enviado al procesador es max(this_floor, actual_billing_amount), por lo que este es, en la práctica, el límite máximo de autorización visible para el cliente cuando la facturación sea 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.
object
Personaliza la apariencia y el comportamiento de la interfaz de checkout.
object
Configura funciones y comportamientos específicos para la sesión de checkout.
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 de webhook y están disponibles mediante la API.
Las respuestas de los clientes a los campos personalizados se incluyen en:
  • Webhooks: payment.succeeded, subscription.active y otras cargas de eventos relevantes contienen la matriz custom_field_responses
  • Respuestas de la API: Los objetos de pago y suscripción incluyen custom_field_responses
object
Configuración adicional para sesiones de checkout que contienen productos de suscripción.

Ejemplos de uso

Checkout sencillo de un solo producto

Carrito con varios productos

Suscripción con periodo de prueba

Checkout preconfirmado

Checkout con anulación de moneda

Métodos de pago guardados para clientes recurrentes

Checkout B2B con recopilación del ID fiscal

Checkout con tema oscuro y códigos de descuento acumulables

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.

Checkout 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).

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

Enlaces cortos para URL de pago más limpias

Omitir la página de confirmación del pago y redirigir inmediatamente

Forzar un idioma

Recopilar campos personalizados

Previsualizar sesiones de checkout

Usa el endpoint Preview Checkout Session para calcular precios, impuestos y totales antes de crear una sesión. 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 con respecto al momento actual: now + trial period cuando se aplica una prueba; de lo contrario, now + one payment frequency. El campo se omite para carritos exclusivamente de 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 consultar el total con impuestos que se debe pagar hoy.
Si usas Dynamic Links, Checkout Sessions ofrece más flexibilidad. Con Dynamic Links, debías proporcionar la dirección de facturación completa del cliente. Con Checkout Sessions, puedes enviar la información que tengas y el flujo de checkout recopila el resto. Por ejemplo:
  • Proporciona únicamente el país de facturación del cliente y el checkout recopila los datos restantes.
  • O proporciona toda la información y establece confirm: true para ir directamente a la página de pago.
La migración es sencilla: actualiza tu integración para usar la API de Checkout Sessions o el método del SDK, ajusta la carga de la solicitud para que coincida con el formato de Checkout Sessions y listo. No se requiere ninguna gestión adicional.

Recursos relacionados

Overlay Checkout

Abrir el checkout como una superposición modal en tu página

Inline Checkout

Integrar el checkout directamente en tu página

Mobile Integration

Integrar el checkout en aplicaciones móviles nativas

Webhooks

Escuchar eventos de pagos y suscripciones

Payment Methods

Métodos de pago compatibles por región

Subscriptions

Facturación recurrente y gestión de suscripciones
Última modificación el 26 de septiembre de 2026