Zum Hauptinhalt springen

Übersicht

Das Dodo Payments Checkout SDK bietet eine nahtlose Möglichkeit, unser Zahlungs-Overlay in Ihre Webanwendung zu integrieren. Es wurde mit TypeScript und modernen Webstandards entwickelt und bietet eine robuste Lösung für die Zahlungsabwicklung mit Echtzeit-Ereignisverarbeitung und anpassbaren Themen.
Overlay-Checkout-Coverbild

Demo

Interactive Demo

Sehen Sie den Overlay-Checkout in Aktion mit unserem Live-Demo.

Schnellstart

Starten Sie mit dem Dodo Payments Checkout SDK in nur wenigen Codezeilen:
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"
});
Holen Sie sich Ihre Checkout-URL über die create checkout session API.

Schritt-für-Schritt-Integrationsanleitung

1

Install the SDK

Installieren Sie das Dodo Payments Checkout SDK mit Ihrem bevorzugten Paketmanager:
npm install dodopayments-checkout
2

Initialize the SDK

Initialisieren Sie das SDK in Ihrer Anwendung, typischerweise in Ihrer Hauptkomponente oder dem Einstiegspunkt der App:
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;
    }
  },
});
Initialisieren Sie das SDK immer, bevor Sie versuchen, den Checkout zu öffnen. Die Initialisierung sollte einmal erfolgen, wenn Ihre Anwendung geladen wird.
3

Create a Checkout Button Component

Erstellen Sie eine Komponente, die das Checkout-Overlay öffnet:
// 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>
  );
}
4

Add Checkout to Your Page

Verwenden Sie die Checkout-Button-Komponente in Ihrer Anwendung:
// 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

Handle Success and Failure Pages

Erstellen Sie Seiten, um Checkout-Weiterleitungen zu behandeln:
// 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

Test Your Integration

  1. Starten Sie Ihren Entwicklungsserver:
npm run dev
  1. Testen Sie den Checkout-Fluss:
    • Klicken Sie auf die Checkout-Schaltfläche
    • Überprüfen Sie, ob das Overlay erscheint
    • Testen Sie den Zahlungsfluss mit Testanmeldeinformationen
    • Bestätigen Sie, dass die Weiterleitungen korrekt funktionieren
Sie sollten Checkout-Ereignisse in Ihrer Browserkonsole protokolliert sehen.
7

Go Live

Wenn Sie bereit für die Produktion sind:
  1. Ändern Sie den Modus zu 'live':
DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. Aktualisieren Sie Ihre Checkout-URLs, um Live-Checkout-Sitzungen von Ihrem Backend zu verwenden
  2. Testen Sie den gesamten Fluss in der Produktion
  3. Überwachen Sie Ereignisse und Fehler

API-Referenz

Konfiguration

Initialisierungsoptionen

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
OptionTypErforderlichBeschreibung
mode"test" | "live"YesUmgebungsmodus: 'test' für die Entwicklung, 'live' für die Produktion
displayType"overlay" | "inline"NoAnzeigeart: 'overlay' für modal Checkout (Standard), 'inline' für eingebetteten Checkout
onEventfunctionYesCallback-Funktion zur Verarbeitung von Checkout-Ereignissen

Checkout-Optionen

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}
OptionTypErforderlichBeschreibung
checkoutUrlstringYesCheckout-Session-URL von der create checkout session API
options.showTimerbooleanNoZeigen oder verbergen Sie den Checkout-Timer. Standardmäßig true. Wenn deaktiviert, erhalten Sie das checkout.link_expired-Ereignis, wenn die Sitzung abläuft.
options.showSecurityBadgebooleanNoZeigen oder verbergen Sie das Sicherheitsabzeichen. Standardmäßig true.
options.manualRedirectbooleanNoWenn aktiviert, leitet der Checkout nach Abschluss nicht automatisch weiter. Stattdessen erhalten Sie checkout.status und checkout.redirect_requested-Ereignisse, um die Weiterleitung selbst zu steuern.

Methoden

Checkout öffnen

Öffnet das Checkout-Overlay mit der angegebenen Checkout-Sitzungs-URL.
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
Sie können auch zusätzliche Optionen übergeben, um das Checkout-Verhalten anzupassen:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});
Wenn Sie manualRedirect verwenden, behandeln Sie den Abschluss des Checkouts in Ihrem onEvent-Callback:
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
    }
  },
});

Kasse schließen

Schließt das Kassenoverlay programmgesteuert.
DodoPayments.Checkout.close();

Status überprüfen

Gibt an, ob das Kassenoverlay derzeit geöffnet ist.
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Ereignisse

Das SDK bietet Echtzeitereignisse, auf die Sie über den onEvent-Callback reagieren können:

Daten zum Kassenstatus-Ereignis

Wenn manualRedirect aktiviert ist, erhalten Sie das checkout.status-Ereignis mit folgenden Daten:
interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Daten zum angeforderten Kassenumleitungsereignis

Wenn manualRedirect aktiviert ist, erhalten Sie das checkout.redirect_requested-Ereignis mit folgenden Daten:
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.form_ready":
        // Checkout form is ready for user input
        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;
    }
  }
});
EreignistypBeschreibung
checkout.openedCheckout-Overlay wurde geöffnet
checkout.form_readyDas Checkout-Formular ist bereit, Benutzereingaben zu empfangen. Nützlich zum Ausblenden von Ladezuständen.
checkout.payment_page_openedDie Zahlungsseite wurde angezeigt
checkout.customer_details_submittedKunden- und Rechnungsdaten wurden übermittelt
checkout.closedCheckout-Overlay wurde geschlossen
checkout.redirectDer Checkout wird eine Weiterleitung durchführen
checkout.errorWährend des Checkouts ist ein Fehler aufgetreten
checkout.link_expiredWird ausgelöst, wenn die Checkout-Sitzung abläuft. Wird nur empfangen, wenn showTimer auf false gesetzt ist.
checkout.statusWird ausgelöst, wenn manualRedirect aktiviert ist. Enthält den Checkout-Status (succeeded, failed oder processing).
checkout.redirect_requestedWird ausgelöst, wenn manualRedirect aktiviert ist. Enthält die URL, zu der der Kunde weitergeleitet werden soll.

Implementierungsoptionen

Installation über Paketmanager

Installieren Sie über npm, yarn oder pnpm, wie im Schritt-für-Schritt-Integrationsleitfaden gezeigt.

CDN-Implementierung

Für eine schnelle Integration ohne Build-Schritt können Sie unser CDN verwenden:
<!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>

Theme-Anpassung

Sie können das Aussehen des Checkouts anpassen, indem Sie ein themeConfig-Objekt im options-Parameter übergeben, wenn Sie den Checkout öffnen. Die Theme-Konfiguration unterstützt sowohl Hell- als auch Dunkelmodus, sodass Sie Farben, Rahmen, Text, Schaltflächen und Border-Radius anpassen können.
Dieser Abschnitt behandelt die clientseitige Themenkonfiguration mithilfe des Checkout SDK. Du kannst Themen auch serverseitig konfigurieren, wenn du eine Checkout-Session über die API mit dem theme_config-Parameter erstellst. Siehe Checkout Theme Customization für Konfiguration auf API-Ebene oder verwende die Design page im Dashboard, um Themen visuell mit Live-Vorschau zu konfigurieren.

Grundlegende Theme-Konfiguration

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Vollständige Theme-Konfiguration

Alle verfügbaren Theme-Eigenschaften:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Nur Hellmodus

Wenn Sie nur das helle Theme anpassen möchten:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Nur Dunkelmodus

Wenn Sie nur das dunkle Theme anpassen möchten:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Teilweises Theme-Override

Sie können nur bestimmte Eigenschaften überschreiben. Der Checkout verwendet Standardwerte für nicht angegebene Eigenschaften:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Theme-Konfiguration mit anderen Optionen

Sie können die Theme-Konfiguration mit anderen Checkout-Optionen kombinieren:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

TypeScript-Typen

Für TypeScript-Nutzer werden alle Theme-Konfigurationstypen exportiert:
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Fehlerbehandlung

Das SDK liefert detaillierte Fehlerinformationen über das Ereignissystem. Implementieren Sie stets eine ordnungsgemäße Fehlerbehandlung in Ihrem onEvent-Callback:
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");
    }
  }
});
Behandeln Sie stets das checkout.error-Ereignis, um eine gute Nutzererfahrung bei Fehlern sicherzustellen.

Best Practices

  1. Einmal initialisieren: Initialisieren Sie das SDK einmal beim Laden Ihrer Anwendung, nicht bei jedem Checkout-Versuch
  2. Fehlerbehandlung: Implementieren Sie stets eine ordnungsgemäße Fehlerbehandlung in Ihrem Ereignis-Callback
  3. Testmodus: Verwenden Sie test während der Entwicklung und wechseln Sie erst zu live, wenn Sie produktionsbereit sind
  4. Ereignisbehandlung: Verarbeiten Sie alle relevanten Ereignisse für ein vollständiges Benutzererlebnis
  5. Gültige URLs: Verwenden Sie immer gültige Checkout-URLs aus der Create Checkout Session API
  6. TypeScript: Verwenden Sie TypeScript für bessere Typensicherheit und Entwicklererfahrung
  7. Ladezustände: Zeigen Sie Ladezustände, während der Checkout geöffnet wird, um die UX zu verbessern
  8. Manuelle Weiterleitungen: Verwenden Sie manualRedirect, wenn Sie benutzerdefinierte Kontrolle über die Navigation nach dem Checkout benötigen
  9. Timer-Verwaltung: Deaktivieren Sie den Timer (showTimer: false), wenn Sie den Sitzungsablauf manuell behandeln möchten

Fehlerbehebung

Mögliche Ursachen:
  • SDK wurde nicht initialisiert, bevor open() aufgerufen wurde
  • Ungültige Checkout-URL
  • JavaScript-Fehler in der Konsole
  • Netzwerkverbindungsprobleme
Lösungen:
  • Überprüfen Sie, dass das SDK initialisiert wird, bevor der Checkout geöffnet wird
  • Prüfen Sie die Konsole auf Fehler
  • Stellen Sie sicher, dass die Checkout-URL gültig ist und von der Create Checkout Session API stammt
  • Überprüfen Sie die Netzwerkverbindung
Mögliche Ursachen:
  • Ereignis-Handler nicht korrekt eingerichtet
  • JavaScript-Fehler verhindern die Ereignisweiterleitung
  • SDK nicht korrekt initialisiert
Lösungen:
  • Bestätigen Sie, dass der Ereignis-Handler korrekt in Initialize() konfiguriert ist
  • Prüfen Sie die Browserkonsole auf JavaScript-Fehler
  • Stellen Sie sicher, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
  • Testen Sie zuerst mit einem einfachen Ereignis-Handler
Mögliche Ursachen:
  • CSS-Konflikte mit den Styles Ihrer Anwendung
  • Theme-Einstellungen wurden nicht korrekt angewendet
  • Probleme mit dem Responsive Design
Lösungen:
  • Überprüfen Sie CSS-Konflikte mit den DevTools des Browsers
  • Stellen Sie sicher, dass die Theme-Einstellungen korrekt sind
  • Testen Sie auf verschiedenen Bildschirmgrößen
  • Stellen Sie sicher, dass keine Z-Index-Konflikte mit dem Overlay bestehen

Aktivierung digitaler Wallets

Für ausführliche Informationen zur Einrichtung von Google Pay und anderen digitalen Wallets siehe die Seite Digital Wallets.
Apple Pay wird im Overlay-Checkout noch nicht unterstützt. Die Unterstützung für Apple Pay kommt bald.

Browser-Unterstützung

Das Dodo Payments Checkout SDK unterstützt die folgenden Browser:
  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • IE11+

Overlay- vs. Inline-Checkout

Wählen Sie den richtigen Checkout-Typ für Ihren Anwendungsfall:
FunktionOverlay-CheckoutInline-Checkout
IntegrationsdichteModal über der SeiteVollständig in die Seite eingebettet
Layout-KontrolleEingeschränktVolle Kontrolle
BrandingGetrennt von der SeiteNahtlos
UmsetzungsaufwandGeringerHöher
Am besten geeignet fürSchnelle Integration, bestehende SeitenIndividuelle Checkout-Seiten, konversionsstarke Abläufe
Verwenden Sie Overlay-Checkout für eine schnellere Integration mit minimalen Änderungen an Ihren bestehenden Seiten. Verwenden Sie Inline-Checkout, wenn Sie maximale Kontrolle über das Checkout-Erlebnis und nahtloses Branding wünschen.

Verwandte Ressourcen

Für weitere Hilfe besuchen Sie unsere Discord-Community oder kontaktieren Sie unser Entwickler-Support-Team.