Pago en Superposición

Descripción general

El SDK de Pago de Dodo Payments proporciona una forma fluida de integrar nuestra superposición de pago en su aplicación web. Construido con TypeScript y estándares web modernos, ofrece una solución robusta para manejar pagos con manejo de eventos en tiempo real y temas personalizables.

Imagen de portada de Pago en Superposición

Demostración

Demostración Interactiva

Vea el pago en superposición en acción con nuestra demostración en vivo.

Inicio Rápido

Comience con el SDK de Pago de Dodo Payments en solo unas pocas líneas de código:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Obtenga su URL de pago desde la API de crear sesión de pago.

Guía de Integración Paso a Paso

Instalar el SDK

Instale el SDK de Pago de Dodo Payments utilizando su gestor de paquetes preferido:

npm install dodopayments-checkout

Inicializar el SDK

Inicialice el SDK en su aplicación, típicamente en su componente principal o punto de entrada de la aplicación:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Siempre inicialice el SDK antes de intentar abrir el pago. La inicialización debe ocurrir una vez cuando su aplicación se carga.

Crear un Componente de Botón de Pago

Cree un componente que abra la superposición de pago:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Agregar Pago a Su Página

Utilice el componente de botón de pago en su aplicación:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Manejar Páginas de Éxito y Fallo

Cree páginas para manejar redirecciones de pago:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Probar Su Integración

Inicie su servidor de desarrollo:

npm run dev

Pruebe el flujo de pago:
- Haga clic en el botón de pago
- Verifique que la superposición aparezca
- Pruebe el flujo de pago utilizando credenciales de prueba
- Confirme que las redirecciones funcionen correctamente

Debería ver eventos de pago registrados en la consola de su navegador.

Ir a Producción

Cuando esté listo para producción:

Cambie el modo a 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Actualice sus URLs de pago para usar sesiones de pago en vivo desde su backend
Pruebe el flujo completo en producción
Monitoree eventos y errores

Referencia de API

Configuración

Opciones de Inicialización

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

Opción	Tipo	Requerido	Descripción
`mode`	`"test" \| "live"`	Sí	Modo de entorno: `'test'` para desarrollo, `'live'` para producción
`displayType`	`"overlay" \| "inline"`	No	Tipo de visualización: `'overlay'` para pago modal (predeterminado), `'inline'` para pago embebido
`onEvent`	`function`	Sí	Función de callback para manejar eventos de pago

Opciones de Pago

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

Opción	Tipo	Requerido	Descripción
`checkoutUrl`	`string`	Sí	URL de sesión de pago de la API de creación de sesión de pago
`options.showTimer`	`boolean`	No	Mostrar u ocultar el temporizador de pago. Por defecto es `true`. Cuando está deshabilitado, 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 pago no redirigirá automáticamente después de la finalización. En su lugar, recibirás los eventos `checkout.status` y `checkout.redirect_requested` para manejar la redirección tú mismo.

Métodos

Abrir Pago

Abre la superposición de pago con la URL de sesión de pago especificada.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

También puedes pasar opciones adicionales para personalizar el comportamiento del pago:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

Al usar manualRedirect, maneja la finalización del pago en tu callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Cerrar Pago

Cierra programáticamente la superposición de pago.

DodoPayments.Checkout.close();

Verificar Estado

Devuelve si la superposición de pago está actualmente abierta.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Eventos

El SDK proporciona eventos en tiempo real a los que puedes escuchar a través del callback onEvent:

Datos del Evento de Estado de Pago

Cuando manualRedirect está habilitado, recibes el evento checkout.status con los siguientes datos:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Datos del Evento de Redirección de Pago Solicitada

Cuando manualRedirect está habilitado, recibes el evento checkout.redirect_requested con los siguientes datos:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Tipo de Evento	Descripción
`checkout.opened`	La superposición de pago se ha abierto
`checkout.payment_page_opened`	La página de pago se ha mostrado
`checkout.customer_details_submitted`	Los detalles del cliente y de facturación se han enviado
`checkout.closed`	La superposición de pago se ha cerrado
`checkout.redirect`	El pago realizará una redirección
`checkout.error`	Ocurrió un error durante el pago
`checkout.link_expired`	Se activa cuando la sesión de pago expira. Solo se recibe cuando `showTimer` está configurado en `false`.
`checkout.status`	Se activa cuando `manualRedirect` está habilitado. Contiene el estado del pago (`succeeded`, `failed`, o `processing`).
`checkout.redirect_requested`	Se activa cuando `manualRedirect` está habilitado. Contiene la URL a la que redirigir al cliente.

Opciones de Implementación

Instalación a través de Gestor 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 nuestra CDN:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Soporte para TypeScript

El SDK está escrito en TypeScript e incluye definiciones de tipo completas. Todas las API públicas están completamente tipadas para una mejor experiencia de desarrollador y soporte de IntelliSense.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

Manejo de Errores

El SDK proporciona información detallada sobre errores a través del sistema de eventos. Siempre implementa un manejo adecuado de errores en tu callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

Siempre maneja el evento checkout.error para proporcionar una buena experiencia de usuario cuando ocurren errores.

Mejores Prácticas

Inicializa una vez: Inicializa el SDK una vez cuando tu aplicación se carga, no en cada intento de pago
Manejo de errores: Siempre implementa un manejo adecuado de errores en tu callback de eventos
Modo de prueba: Usa el modo test durante el desarrollo y cambia a live solo cuando estés listo para producción
Manejo de eventos: Maneja todos los eventos relevantes para una experiencia de usuario completa
URLs válidas: Siempre usa URLs de pago válidas de la API de creación de sesión de pago
TypeScript: Usa TypeScript para una mejor seguridad de tipos y experiencia de desarrollador
Estados de carga: Muestra estados de carga mientras se abre el pago para mejorar la experiencia de usuario
Redirecciones manuales: Usa manualRedirect cuando necesites control personalizado sobre la navegación posterior al pago
Manejo de temporizadores: Desactiva el temporizador (showTimer: false) si deseas manejar la expiración de la sesión manualmente

Solución de Problemas

El pago no se abre

Causas posibles:

SDK no inicializado antes de llamar a open()
URL de pago no válida
Errores de JavaScript en la consola
Problemas de conectividad de red

Soluciones:

Verifica que la inicialización del SDK ocurra antes de abrir el pago
Revisa si hay errores en la consola
Asegúrate de que la URL de pago sea válida y provenga de la API de creación de sesión de pago
Verifica la conectividad de red

Eventos no se activan

Causas posibles:

Manejador de eventos no configurado correctamente
Errores de JavaScript que impiden la propagación de eventos
SDK no inicializado correctamente

Soluciones:

Confirma que el manejador de eventos esté configurado correctamente en Initialize()
Revisa la consola del navegador en busca de errores de JavaScript
Verifica que la inicialización del SDK se haya completado con éxito
Prueba primero con un manejador de eventos simple

Problemas de estilo

Causas posibles:

Conflictos de CSS con los estilos de tu aplicación
Configuraciones de tema no aplicadas correctamente
Problemas de diseño responsivo

Soluciones:

Revisa si hay conflictos de CSS en las herramientas de desarrollo del navegador
Verifica que las configuraciones de tema sean correctas
Prueba en diferentes tamaños de pantalla
Asegúrate de que no haya conflictos de z-index con la superposición

Habilitando Apple Pay

Apple Pay permite a los clientes completar pagos de manera rápida y segura utilizando sus métodos de pago guardados. Cuando está habilitado, los clientes pueden lanzar el modal de Apple Pay directamente desde la superposición de pago en dispositivos compatibles.

Apple Pay es compatible con iOS 17+, iPadOS 17+ y Safari 17+ en macOS.

Para habilitar Apple Pay para tu dominio en producción, sigue estos pasos:

Descargar y subir el archivo de asociación de dominio de Apple Pay

Descarga el archivo de asociación de dominio de Apple Pay.Sube el archivo a tu servidor web en /.well-known/apple-developer-merchantid-domain-association. Por ejemplo, si tu sitio web es example.com, haz que el archivo esté disponible en https://example.com/well-known/apple-developer-merchantid-domain-association.

Solicitar activación de Apple Pay

Envía un correo electrónico a [email protected] con la siguiente información:

La URL de tu dominio de producción (por ejemplo, https://example.com)
Solicitud para habilitar Apple Pay para tu dominio

Recibirás confirmación dentro de 1-2 días hábiles una vez que Apple Pay haya sido habilitado para tu dominio.

Verificar disponibilidad de Apple Pay

Después de recibir la confirmación, prueba Apple Pay en tu pago:

Abre tu pago en un dispositivo compatible (iOS 17+, iPadOS 17+, o Safari 17+ en macOS)
Verifica que el botón de Apple Pay aparezca como una opción de pago
Prueba el flujo completo de pago

Apple Pay debe estar habilitado para tu dominio antes de que aparezca como una opción de pago en producción. Contacta al soporte antes de salir en vivo si planeas ofrecer Apple Pay.

Soporte de 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+