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 Cover Image

Demo

Interaktive Demo

Sehen Sie den Overlay-Checkout in Aktion mit unserer 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 von der create checkout session API.

Schritt-für-Schritt-Integrationsanleitung

1

SDK installieren

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

SDK initialisieren

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

Erstellen Sie eine Checkout-Button-Komponente

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

Fügen Sie den Checkout zu Ihrer Seite hinzu

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

Erfolgs- und Fehlerseiten behandeln

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

Testen Sie Ihre 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 der Konsole Ihres Browsers protokolliert sehen.
7

Live gehen

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"JaUmgebungsmodus: 'test' für Entwicklung, 'live' für Produktion
displayType"overlay" | "inline"NeinAnzeigetyp: 'overlay' für modalen Checkout (Standard), 'inline' für eingebetteten Checkout
onEventfunctionJaCallback-Funktion zur Verarbeitung von Checkout-Ereignissen

Checkout-Optionen

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}
OptionTypErforderlichBeschreibung
checkoutUrlstringJaCheckout-Sitzungs-URL von der create checkout session API
options.showTimerbooleanNeinZeigen oder verbergen Sie den Checkout-Timer. Standardmäßig true. Wenn deaktiviert, erhalten Sie das checkout.link_expired Ereignis, wenn die Sitzung abläuft.
options.showSecurityBadgebooleanNeinZeigen oder verbergen Sie das Sicherheitsabzeichen. Standardmäßig true.
options.manualRedirectbooleanNeinWenn aktiviert, wird der Checkout nach Abschluss nicht automatisch umgeleitet. Stattdessen erhalten Sie checkout.status und checkout.redirect_requested Ereignisse, um die Umleitung 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, verarbeiten Sie den Checkout-Abschluss 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 hören können:

Daten zum Kassenstatus-Ereignis

Wenn manualRedirect aktiviert ist, erhalten Sie das checkout.status Ereignis mit den 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 den 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.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.payment_page_openedZahlungsseite wurde angezeigt
checkout.customer_details_submittedKunden- und Rechnungsdetails wurden übermittelt
checkout.closedCheckout-Overlay wurde geschlossen
checkout.redirectCheckout wird eine Umleitung durchführen
checkout.errorEin Fehler ist während des Checkouts aufgetreten
checkout.link_expiredWird ausgelöst, wenn die Checkout-Sitzung abläuft. 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 umgeleitet 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 Erscheinungsbild des Checkouts anpassen, indem Sie ein themeConfig Objekt im options Parameter beim Öffnen des Checkouts übergeben. Die Themenkonfiguration unterstützt sowohl helle als auch dunkle Modi, sodass Sie Farben, Ränder, Text, Schaltflächen und den Randradius anpassen können.

Grundlegende Themenkonfiguration

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 Themenkonfiguration

Alle verfügbaren Themenattribute:
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 im Lichtmodus

Wenn Sie nur das helle Thema 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 im Dunkelmodus

Wenn Sie nur das dunkle Thema 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",
    },
  },
});

Teilweise Themenüberschreibung

Sie können nur bestimmte Eigenschaften überschreiben. Der Checkout verwendet Standardwerte für Eigenschaften, die Sie nicht angeben:
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
    },
  },
});

Themenkonfiguration mit anderen Optionen

Sie können die Themenkonfiguration 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 sind alle Typen der Themenkonfiguration 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 bietet detaillierte Fehlermeldungen über das Ereignissystem. Implementieren Sie immer 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 immer das checkout.error Ereignis, um eine gute Benutzererfahrung zu gewährleisten, wenn Fehler auftreten.

Best Practices

  1. Einmal initialisieren: Initialisieren Sie das SDK einmal, wenn Ihre Anwendung geladen wird, nicht bei jedem Checkout-Versuch
  2. Fehlerbehandlung: Implementieren Sie immer eine ordnungsgemäße Fehlerbehandlung in Ihrem Ereignis-Callback
  3. Testmodus: Verwenden Sie den test Modus während der Entwicklung und wechseln Sie erst bei Produktionsbereitschaft zu live
  4. Ereignisbehandlung: Behandeln Sie alle relevanten Ereignisse für ein vollständiges Benutzererlebnis
  5. Gültige URLs: Verwenden Sie immer gültige Checkout-URLs von der create checkout session API
  6. TypeScript: Verwenden Sie TypeScript für bessere Typensicherheit und Entwicklererfahrung
  7. Ladezustände: Zeigen Sie Ladezustände an, während der Checkout geöffnet wird, um die Benutzererfahrung zu verbessern
  8. Manuelle Umleitungen: Verwenden Sie manualRedirect wenn Sie eine benutzerdefinierte Kontrolle über die Navigation nach dem Checkout benötigen
  9. Timer-Management: Deaktivieren Sie den Timer (showTimer: false), wenn Sie die Sitzungsablauf manuell verwalten möchten

Fehlersuche

Mögliche Ursachen:
  • SDK nicht initialisiert, bevor open() aufgerufen wird
  • Ungültige Checkout-URL
  • JavaScript-Fehler in der Konsole
  • Netzwerkverbindungsprobleme
Lösungen:
  • Überprüfen Sie, ob die SDK-Initialisierung vor dem Öffnen des Checkouts erfolgt
  • Überprüfen Sie auf Konsolenfehler
  • Stellen Sie sicher, dass die Checkout-URL gültig ist und von der API zum Erstellen von Checkout-Sitzungen stammt
  • Überprüfen Sie die Netzwerkverbindung
Mögliche Ursachen:
  • Ereignishandler nicht richtig eingerichtet
  • JavaScript-Fehler verhindern die Ereignisweiterleitung
  • SDK nicht korrekt initialisiert
Lösungen:
  • Bestätigen Sie, dass der Ereignishandler korrekt im Initialize() konfiguriert ist
  • Überprüfen Sie die Browserkonsole auf JavaScript-Fehler
  • Verifizieren Sie, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
  • Testen Sie zuerst mit einem einfachen Ereignishandler
Mögliche Ursachen:
  • CSS-Konflikte mit Ihren Anwendungsstilen
  • Themen Einstellungen wurden nicht korrekt angewendet
  • Probleme mit responsive Design
Lösungen:
  • Überprüfen Sie auf CSS-Konflikte in den Browser-Entwicklertools
  • Überprüfen Sie, ob die Themen Einstellungen korrekt sind
  • Testen Sie auf verschiedenen Bildschirmgrößen
  • Stellen Sie sicher, dass keine z-index Konflikte mit Overlay bestehen

Aktivierung von digitalen Geldbörsen

Für detaillierte Informationen zur Einrichtung von Apple Pay, Google Pay und anderen digitalen Geldbörsen siehe die Seite über digitale Geldbörsen.

Schnelle Einrichtung für Apple Pay

1

Herunterladen der Domain-Verknüpfungsdatei

2

Aktivierungsanforderung

Sende eine E-Mail an support@dodopayments.com mit deiner Produktionsdomain-URL und fordere die Aktivierung von Apple Pay an.
3

Test nach Bestätigung

Überprüfe nach der Bestätigung, ob Apple Pay an der Kasse erscheint, und teste den gesamten Ablauf.
Apple Pay erfordert die Verifizierung der Domain, bevor es in der Produktion erscheint. Kontaktiere den Support, bevor du live gehst, wenn du planst, Apple Pay anzubieten.

Browser-Unterstützung

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

Overlay- vs. Inline-Checkout

Wähle den richtigen Checkout-Typ für deinen Anwendungsfall:
FunktionOverlay-CheckoutInline-Checkout
IntegrationstiefeModal über der SeiteVollständig in die Seite eingebettet
Layout-KontrolleEingeschränktVolle Kontrolle
BrandingGetrennt von der SeiteNahtlos
ImplementierungsaufwandGeringerHöher
Am besten geeignet fürSchnelle Integration, bestehende SeitenAnpassbare Checkout-Seiten, hochkonvertierende Abläufe
Verwende Overlay-Checkout für eine schnellere Integration mit minimalen Änderungen an deinen bestehenden Seiten. Verwende Inline-Checkout, wenn du maximale Kontrolle über die Checkout-Erfahrung und nahtloses Branding wünschst.

Verwandte Ressourcen

Für weitere Hilfe besuche unsere Discord-Community oder kontaktiere unser Entwickler-Support-Team.