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.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
API Response
All methods return: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:
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.Campos opcionales
Customer Information
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
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.Payment Configuration
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.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.
Session Management
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: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_idpara procesar el cargo inmediatamente - La sesión caduca después de 15 minutos en lugar de 24 horas
- Se requiere un
customer_idexistente si se proporcionapayment_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
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.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 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.UI Customization
UI Customization
object
Personaliza la apariencia y el comportamiento de la interfaz de checkout.
Feature Flags
Feature Flags
object
Configura funciones y comportamientos específicos para la sesión de checkout.
Custom Fields
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 de webhook y están disponibles mediante la API.
- Webhooks:
payment.succeeded,subscription.activey otras cargas de eventos relevantes contienen la matrizcustom_field_responses - Respuestas de la API: Los objetos de pago y suscripción incluyen
custom_field_responses
Subscription Configuration
Subscription Configuration
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.- Node.js SDK
- Python SDK
- REST API
Migrar desde Dynamic Links
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: truepara ir directamente a la página de pago.
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