Saltar al contenido principal

​
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'
  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

1

Instalar el SDK

Instale el SDK de Pago de Dodo Payments utilizando su gestor de paquetes preferido:
npm install dodopayments-checkout
2

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
  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.
3

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",
      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>
  );
}
4

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>
  );
}
5

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>
  );
}
6

Probar Su Integración

  1. Inicie su servidor de desarrollo:
npm run dev
  1. 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.
7

Ir a Producción

Cuando esté listo para producción:
  1. Cambie el modo a 'live':
DodoPayments.Initialize({
  mode: "live",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. Actualice sus URLs de pago para usar sesiones de pago en vivo desde su backend
  2. Pruebe el flujo completo en producción
  3. Monitoree eventos y errores

​
Referencia de API

​
Configuración

​
Opciones de Inicialización

interface InitializeOptions {
  mode: "test" | "live";
  onEvent: (event: CheckoutEvent) => void;
}
OpciónTipoRequeridoDescripción
mode"test" | "live"SíModo de entorno: 'test' para desarrollo, 'live' para producción
onEventfunctionSíFunción de callback para manejar eventos de pago

​
Opciones de Pago

interface CheckoutOptions {
  checkoutUrl: string;
}
OpciónTipoRequeridoDescripción
checkoutUrlstringSíURL de sesión de pago de la API de crear sesión de pago

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

​
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 puede escuchar a través de la onEvent callback: 
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;
    }
  }
});
Tipo de EventoDescripción
checkout.openedLa superposición de pago ha sido abierta
checkout.payment_page_openedLa página de pago ha sido mostrada
checkout.customer_details_submittedLos detalles del cliente y de facturación han sido enviados
checkout.closedLa superposición de pago ha sido cerrada
checkout.redirectEl pago realizará una redirección
checkout.errorOcurrió un error durante el pago

​
Opciones de Implementación

​
Instalación con Gestor de Paquetes

Instale 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, puede usar nuestro 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
            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",
  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 implemente un manejo adecuado de errores en su onEvent callback: 
DodoPayments.Initialize({
  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
    }
  }
});
Siempre maneje el evento checkout.error para proporcionar una buena experiencia de usuario cuando ocurren errores.

​
Mejores Prácticas

  1. Inicializar una vez: Inicialice el SDK una vez cuando su aplicación se carga, no en cada intento de pago
  2. Manejo de errores: Siempre implemente un manejo adecuado de errores en su callback de eventos
  3. Modo de prueba: Use el modo test durante el desarrollo y cambie a live solo cuando esté listo para producción
  4. Manejo de eventos: Maneje todos los eventos relevantes para una experiencia de usuario completa
  5. URLs válidas: Siempre use URLs de pago válidas de la API de crear sesión de pago
  6. TypeScript: Use TypeScript para una mejor seguridad de tipos y experiencia de desarrollador
  7. Estados de carga: Muestre estados de carga mientras se abre el pago para mejorar la experiencia de usuario

​
Solución de Problemas

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:
  • Verifique que la inicialización del SDK ocurra antes de abrir el pago
  • Verifique si hay errores en la consola
  • Asegúrese de que la URL de pago sea válida y provenga de la API de crear sesión de pago
  • Verifique la conectividad de red
Causas posibles:
  • Manejador de eventos no configurado correctamente
  • Errores de JavaScript que impiden la propagación de eventos
  • SDK no inicializado correctamente
Soluciones:
  • Confirme que el manejador de eventos esté configurado correctamente en Initialize()
  • Verifique la consola del navegador en busca de errores de JavaScript
  • Verifique que la inicialización del SDK se haya completado con éxito
  • Pruebe primero con un manejador de eventos simple
Causas posibles:
  • Conflictos de CSS con los estilos de su aplicación
  • Configuraciones de tema no aplicadas correctamente
  • Problemas de diseño responsivo
Soluciones:
  • Verifique si hay conflictos de CSS en las herramientas de desarrollo del navegador
  • Verifique que las configuraciones de tema sean correctas
  • Pruebe en diferentes tamaños de pantalla
  • Asegúrese de que no haya conflictos de z-index con la superposición

​
Soporte de Navegadores

El SDK de Pago de Dodo Payments es compatible con los siguientes navegadores:
  • Chrome (última versión)
  • Firefox (última versión)
  • Safari (última versión)
  • Edge (última versión)
  • IE11+
Apple Pay no es actualmente compatible con la experiencia de pago en superposición. Planeamos agregar soporte para Apple Pay en una futura versión.
Para más ayuda, visite nuestra comunidad de Discord o contacte a nuestro equipo de soporte para desarrolladores.