Descripción general
El pago en línea te permite crear experiencias de pago completamente integradas que se mezclan sin problemas con tu sitio web o aplicación. A diferencia del pago en superposición, que se abre como un modal sobre tu página, el pago en línea incrusta el formulario de pago directamente en el diseño de tu página. Usando el pago en línea, puedes:- Crear experiencias de pago que están completamente integradas con tu aplicación o sitio web
- Permitir que Dodo Payments capture de forma segura la información del cliente y de pago en un marco de pago optimizado
- Mostrar artículos, totales y otra información de Dodo Payments en tu página
- Usar métodos y eventos del SDK para construir experiencias de pago avanzadas

Cómo funciona
El pago en línea funciona incrustando un marco seguro de Dodo Payments en tu sitio web o aplicación. El marco de pago se encarga de recopilar la información del cliente y capturar los detalles de pago. Tu página muestra la lista de artículos, totales y opciones para cambiar lo que hay en el pago. El SDK permite que tu página y el marco de pago interactúen entre sí. Dodo Payments crea automáticamente una suscripción cuando se completa un pago, lista para que la provisionen.El marco de inline checkout gestiona de forma segura toda la información de pago sensible, garantizando el cumplimiento de PCI sin que necesites certificación adicional.
¿Qué hace que un buen pago en línea?
Es importante que los clientes sepan de quién están comprando, qué están comprando y cuánto están pagando. Para construir un pago en línea que sea conforme y optimizado para la conversión, tu implementación debe incluir:
- Información recurrente: Si es recurrente, con qué frecuencia se repite y el total a pagar en la renovación. Si es una prueba, cuánto dura la prueba.
- Descripciones de artículos: Una descripción de lo que se está comprando.
- Totales de transacción: Totales de transacción, incluyendo subtotal, total de impuestos y total general. Asegúrate de incluir también la moneda.
- Pie de página de Dodo Payments: El marco completo de pago en línea, incluyendo el pie de página de pago que tiene información sobre Dodo Payments, nuestros términos de venta y nuestra política de privacidad.
- Política de reembolso: Un enlace a tu política de reembolso, si difiere de la política de reembolso estándar de Dodo Payments.
Viaje del cliente
El flujo de pago está determinado por la configuración de tu sesión de pago. Dependiendo de cómo configures la sesión de pago, los clientes experimentarán un pago que puede presentar toda la información en una sola página o a través de múltiples pasos.Customer opens checkout
Puedes abrir el pago en línea pasando artículos o una transacción existente. Usa el SDK para mostrar y actualizar la información en la página, y métodos del SDK para actualizar artículos basados en la interacción del cliente.

Customer enters their details
El pago en línea primero pide a los clientes que ingresen su dirección de correo electrónico, seleccionen su país y (donde sea necesario) ingresen su código postal. Este paso recopila toda la información necesaria para determinar impuestos y opciones de pago disponibles.Puedes prellenar los detalles del cliente y presentar direcciones guardadas para agilizar la experiencia.
Customer selects payment method
Después de ingresar sus datos, se presentan a los clientes los métodos de pago disponibles y el formulario de pago. Las opciones pueden incluir tarjeta de crédito o débito, PayPal, Apple Pay, Google Pay y otros métodos de pago locales según su ubicación.Muestra los métodos de pago guardados si están disponibles para acelerar el pago.

Checkout completed
Dodo Payments dirige cada pago al mejor adquirente para esa venta para obtener la mejor oportunidad de éxito. Los clientes ingresan a un flujo de éxito que puedes construir.

Inicio Rápido
Comienza con el Pago en Línea de Dodo Payments en solo unas pocas líneas de código:Guía de Integración Paso a Paso
Initialize the SDK for Inline Display
Inicializa el SDK y especifica
displayType: 'inline'. También debes escuchar el evento checkout.breakdown para actualizar tu interfaz de usuario con los cálculos de impuestos y totales en tiempo real.Open the Checkout
Llama a
DodoPayments.Checkout.open() con el checkoutUrl y el elementId de tu contenedor:Test Your Integration
- Inicia tu servidor de desarrollo:
- Prueba el flujo de pago:
- Ingresa tu correo electrónico y detalles de dirección en el marco en línea.
- Verifica que tu resumen de pedido personalizado se actualice en tiempo real.
- Prueba el flujo de pago usando credenciales de prueba.
- Confirma que las redirecciones funcionen correctamente.
Deberías ver eventos
checkout.breakdown registrados en la consola del navegador si agregaste un console.log en la devolución onEvent.Ejemplo Completo en React
Este ejemplo muestra cómo implementar un resumen de pedido personalizado junto al inline checkout, manteniéndolos sincronizados mediante el eventocheckout.breakdown.
Referencia de API
Configuración
Opciones de Inicialización
| Opción | Tipo | Requerido | Descripción |
|---|---|---|---|
mode | "test" | "live" | Sí | Modo de entorno. |
displayType | "inline" | "overlay" | Sí | Debe establecerse en "inline" para incrustar el checkout. |
onEvent | function | Sí | Función de devolución para manejar eventos del checkout. |
Opciones de Pago
| Opción | Tipo | Requerido | Descripción |
|---|---|---|---|
checkoutUrl | string | Sí | URL de la sesión de pago. |
elementId | string | Sí | El id del elemento DOM donde se debe representar el proceso de pago. |
options.showTimer | boolean | No | Mostrar u ocultar el temporizador de pago. Por defecto es true. Cuando está desactivado, recibirás el evento checkout.link_expired cuando la sesión expire. |
options.showSecurityBadge | boolean | No | Mostrar u ocultar la insignia de seguridad. Por defecto es true. |
options.manualRedirect | boolean | No | Cuando está habilitado, el proceso de pago no redirigirá automáticamente después de completarse. En su lugar, recibirás los eventos checkout.status e checkout.redirect_requested para encargarte tú mismo de la redirección. |
options.payButtonText | string | No | Texto personalizado para mostrar en el botón de pago. |
options.fontSize | FontSize | No | Tamaño de fuente global para el proceso de pago. |
options.fontWeight | FontWeight | No | Peso de fuente global para el proceso de pago. |
Métodos
Abrir Pago
Abre el marco de pago en el contenedor especificado.manualRedirect, maneja la finalización del checkout en tu callback onEvent:
Cerrar Pago
Elimina programáticamente el marco de pago y limpia los oyentes de eventos.Verificar Estado
Devuelve si el marco de pago está actualmente inyectado.Eventos
El SDK proporciona eventos en tiempo real a través del callbackonEvent. Para el inline checkout, checkout.breakdown es especialmente útil para sincronizar tu UI.
| Tipo de evento | Descripción |
|---|---|
checkout.opened | El marco del checkout se ha cargado. |
checkout.form_ready | El formulario del checkout está listo para recibir datos del usuario. Útil para ocultar estados de carga y mostrar la interfaz del checkout. |
checkout.breakdown | Se dispara cuando se actualizan precios, impuestos o descuentos. |
checkout.customer_details_submitted | Los datos del cliente han sido enviados. |
checkout.pay_button_clicked | Se dispara cuando el cliente hace clic en el botón de pagar. Útil para analítica y seguimiento de embudos de conversión. |
checkout.redirect | El checkout realizará una redirección (por ejemplo, a una página bancaria). |
checkout.error | Ocurrió un error durante el checkout. |
checkout.link_expired | Se dispara cuando expira la sesión del checkout. Solo se recibe cuando showTimer está establecido en false. |
checkout.status | Se dispara cuando manualRedirect está habilitado. Contiene el estado del checkout (succeeded, failed o processing). |
checkout.redirect_requested | Se dispara cuando manualRedirect está habilitado. Contiene la URL para redirigir al cliente. |
Datos de Desglose del Pago
El eventocheckout.breakdown proporciona los siguientes datos:
Datos del Evento de Estado del Pago
CuandomanualRedirect está habilitado, recibes el evento checkout.status con los siguientes datos:
Datos del Evento de Redirección del Pago Solicitada
CuandomanualRedirect está habilitado, recibes el evento checkout.redirect_requested con los siguientes datos:
Entendiendo el Evento de Desglose
El eventocheckout.breakdown es la forma principal de mantener la UI de tu aplicación sincronizada con el estado del checkout de Dodo Payments.
Cuándo se activa:
- En la inicialización: Inmediatamente después de que el marco de pago se carga y está listo.
- En el cambio de dirección: Cada vez que el cliente selecciona un país o ingresa un código postal que resulta en un recálculo de impuestos.
| Campo | Descripción |
|---|---|
subTotal | La suma de todos los artículos de la sesión antes de aplicar descuentos o impuestos. |
discount | El valor total de todos los descuentos aplicados. |
tax | El importe de impuestos calculado. En el modo inline, esto se actualiza dinámicamente según el usuario interactúa con los campos de dirección. |
total | El resultado matemático de subTotal - discount + tax en la moneda base de la sesión. |
currency | El código ISO de la moneda (por ejemplo, "USD") para los valores estándar de subtotal, descuento e impuesto. |
finalTotal | El importe real que se cobra al cliente. Esto puede incluir ajustes de cambio o tarifas de métodos de pago locales que no forman parte del desglose básico del precio. |
finalTotalCurrency | La moneda en la que el cliente paga realmente. Esto puede diferir de currency si se aplica paridad de poder adquisitivo o conversión a moneda local. |
- Formato de moneda: Los precios siempre se devuelven como enteros en la unidad monetaria más pequeña (por ejemplo, centavos para USD, yenes para JPY). Para mostrarlos, divide entre 100 (o la potencia de 10 correspondiente) o usa una biblioteca de formateo como
Intl.NumberFormat. - Manejo de estados iniciales: Cuando el checkout se carga por primera vez,
taxediscountpueden estar0onullhasta que el usuario proporcione su información de facturación o aplique un código. Tu UI debe manejar estos estados con elegancia (por ejemplo, mostrando un guion—u ocultando la fila). - El “Total final” vs “Total”: Mientras que
totalte ofrece el cálculo estándar del precio,finalTotales la fuente de verdad para la transacción. SifinalTotalestá presente, refleja exactamente lo que se cobrará en la tarjeta del cliente, incluidos los ajustes dinámicos. - Retroalimentación en tiempo real: Usa el campo
taxpara mostrar a los usuarios que los impuestos se calculan en tiempo real. Esto otorga una sensación “en vivo” a tu página de checkout y reduce la fricción durante el paso de ingreso de dirección.
Opciones de Implementación
Instalación a través de Gestores de Paquetes
Instala a través de npm, yarn o pnpm como se muestra en la Guía de Integración Paso a Paso.Implementación CDN
Para una integración rápida sin un paso de construcción, puedes usar nuestro CDN:Actualizar método de pago
El proceso de pago en línea admite actualizaciones de método de pago para suscripciones. Cuando un cliente necesita actualizar su método de pago —ya sea para una suscripción activa o para reactivar una suscripción en espera— puedes mostrar el flujo de actualización directamente dentro del diseño de la página.Cómo funciona
- Llama a la API de actualización de método de pago para obtener un
payment_link:
- Pasa el
payment_linkdevuelto comocheckoutUrlpara abrir el proceso de pago en línea:
Para suscripciones en espera
Al actualizar el método de pago de una suscripción en estadoon_hold, Dodo Payments crea automáticamente un cargo por cualquier saldo pendiente. Supervisa los webhooks payment.succeeded e subscription.active para confirmar la reactivación.
Manejo de errores
El SDK proporciona información detallada de errores a través del sistema de eventos. Siempre implementa un manejo adecuado de errores en tu callbackonEvent:
Mejores prácticas
- Diseño responsivo: Asegúrate de que el elemento contenedor tenga suficiente ancho y alto. El iframe normalmente se expandirá para llenar su contenedor.
- Sincronización: Usa el evento
checkout.breakdownpara mantener tu resumen de pedido personalizado o las tablas de precios sincronizadas con lo que el usuario ve en el marco de pago. - Estados esqueléticos: Muestra un indicador de carga en tu contenedor hasta que se dispare el evento
checkout.opened. - Limpieza: Llama a
DodoPayments.Checkout.close()cuando tu componente se desmonte para limpiar el iframe y los escuchadores de eventos.
Para implementaciones en modo oscuro, se recomienda usar
#0d0d0d como color de fondo para una integración visual óptima con el marco de pago en línea.Validación del estado del pago
Por qué la validación del lado del servidor es esencial
Aunque eventos del proceso de pago en línea comocheckout.status brindan retroalimentación en tiempo real, no deben ser tu única fuente de verdad para el estado del pago. Problemas de red, fallas del navegador o que los usuarios cierren la página pueden causar que los eventos se pierdan. Para garantizar una validación de pago confiable:
- Tu servidor debe escuchar eventos de webhooks - Dodo Payments envía webhooks para los cambios en el estado de pago
- Implementa un mecanismo de sondeo - Tu frontend debe sondear a tu servidor para obtener actualizaciones de estado
- Combina ambos enfoques - Usa webhooks como fuente primaria y los sondeos como respaldo
Arquitectura recomendada
Pasos de implementación
1. Escucha los eventos de pago - Cuando el usuario hace clic en pagar, comienza a prepararte para verificar el estado:payment.succeeded o payment.failed. Consulta nuestra documentación de webhooks para más detalles.
Manejo de redirecciones (3DS, Google Pay, UPI)
Al usarmanualRedirect: true, ciertos métodos de pago requieren redirigir al usuario fuera de tu página para autenticación:
- 3D Secure (3DS) - Autenticación de tarjeta
- Google Pay - Autenticación de billetera en algunos flujos
- UPI - Redirecciones de métodos de pago indios
checkout.redirect_requested. Redirige al usuario a la URL proporcionada:
- Verifica si el usuario regresa tras una redirección (por ejemplo, mediante
sessionStorage) - Comienza a sondear a tu servidor por el estado de pago confirmado
- Muestra un estado de “Verificando el pago…” mientras sondeas
- Muestra una interfaz de éxito o fallo basada en el estado confirmado por el servidor
Solución de problemas
Checkout frame is not appearing
Checkout frame is not appearing
- Verifica que
elementIdcoincida con elidde undivque realmente exista en el DOM. - Asegúrate de que
displayType: 'inline'fue pasado aInitialize. - Comprueba que el
checkoutUrlsea válido.
Taxes are not updating in my UI
Taxes are not updating in my UI
- Asegúrate de estar escuchando el evento
checkout.breakdown. - Los impuestos solo se calculan después de que el usuario ingresa un país y código postal válidos en el marco de pago.
Activar billeteras digitales
Para obtener información detallada sobre cómo configurar Apple Pay, Google Pay y otras billeteras digitales, consulta la página de Billeteras digitales.Configuración rápida de Apple Pay
Download domain association file
Descarga el archivo de asociación de dominio de Apple Pay.
Request activation
Envía un correo electrónico a support@dodopayments.com con la URL de tu dominio de producción y solicita la activación de Apple Pay.
Compatibilidad con navegadores
El SDK de Dodo Payments Checkout es compatible con los siguientes navegadores:- Chrome (última versión)
- Firefox (última versión)
- Safari (última versión)
- Edge (última versión)
- IE11+
Proceso de pago en línea vs superposición
Elige el tipo de proceso de pago adecuado para tu caso de uso:| Funcionalidad | Proceso de pago en línea | Proceso de pago en superposición |
|---|---|---|
| Profundidad de integración | Totalmente integrado en la página | Modal sobre la página |
| Control de diseño | Control total | Limitado |
| Branding | Sin fisuras | Independiente de la página |
| Esfuerzo de implementación | Mayor | Menor |
| Ideal para | Páginas de pago personalizadas, flujos de alta conversión | Integración rápida, páginas existentes |
Recursos relacionados
Overlay Checkout
Usa el proceso de pago en superposición para una integración rápida basada en modales.
Checkout Sessions API
Crea sesiones de pago para impulsar tus experiencias de checkout.
Webhooks
Gestiona los eventos de pago del lado del servidor con webhooks.
Integration Guide
Guía completa para integrar Dodo Payments.
