Overlay Checkout - Dodo Payments Documentation

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

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

Install the SDK

Installieren Sie das Dodo Payments Checkout SDK mit Ihrem bevorzugten Paketmanager:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

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.

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

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

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

Test Your Integration

Starten Sie Ihren Entwicklungsserver:

npm run dev

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.

Go Live

Wenn Sie bereit für die Produktion sind:

Ändern Sie den Modus zu 'live':

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

Aktualisieren Sie Ihre Checkout-URLs, um Live-Checkout-Sitzungen von Ihrem Backend zu verwenden
Testen Sie den gesamten Fluss in der Produktion
Überwachen Sie Ereignisse und Fehler

API-Referenz

Konfiguration

Initialisierungsoptionen

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

Option	Typ	Erforderlich	Beschreibung
`mode`	`"test" \| "live"`	Yes	Umgebungsmodus: `'test'` für die Entwicklung, `'live'` für die Produktion
`displayType`	`"overlay" \| "inline"`	No	Anzeigeart: `'overlay'` für modal Checkout (Standard), `'inline'` für eingebetteten Checkout
`onEvent`	`function`	Yes	Callback-Funktion zur Verarbeitung von Checkout-Ereignissen

Checkout-Optionen

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

Option	Type	Required	Description
`checkoutUrl`	`string`	Ja	Checkout-Session-URL von der Checkout-Session-API erstellen
`options.showTimer`	`boolean`	Nein	Den Checkout-Timer anzeigen oder ausblenden. Standardwert ist `true`. Wenn deaktiviert, erhalten Sie das `checkout.link_expired`-Ereignis, wenn die Sitzung abläuft.
`options.showSecurityBadge`	`boolean`	Nein	Das Sicherheitsabzeichen anzeigen oder ausblenden. Standardwert ist `true`.

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

Checkout schließen

Schließt das Checkout-Overlay programmgesteuert.

DodoPayments.Checkout.close();

Status überprüfen

Gibt zurück, ob das Checkout-Overlay derzeit geöffnet ist.

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

Ereignisse

Das SDK bietet Echtzeit-Ereignisse, die Sie über den onEvent-Callback abhören können:

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

Ereignistyp	Beschreibung
`checkout.opened`	Checkout-Overlay wurde geöffnet
`checkout.form_ready`	Checkout-Formular ist bereit für Benutzereingaben. Nützlich zum Ausblenden von Ladezuständen.
`checkout.payment_page_opened`	Zahlungsseite wurde angezeigt
`checkout.customer_details_submitted`	Kunden- und Rechnungsdaten wurden übermittelt
`checkout.closed`	Checkout-Overlay wurde geschlossen
`checkout.redirect`	Checkout wird eine Weiterleitung durchführen
`checkout.error`	Ein Fehler ist während des Checkouts aufgetreten
`checkout.link_expired`	Wird ausgelöst, wenn die Checkout-Sitzung abläuft. Nur empfangen, wenn `showTimer` auf `false` gesetzt ist.

Implementierungsoptionen

Paketmanager-Installation

Installieren Sie über npm, yarn oder pnpm wie im Step-by-Step Integration Guide gezeigt.

CDN-Implementierung

Für eine schnelle Integration ohne Build-Schritt können Sie unser CDN nutzen:

<!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>

Thema-Anpassung

Sie können das Erscheinungsbild des Checkouts anpassen, indem Sie ein themeConfig-Objekt im options-Parameter übergeben, wenn Sie das Checkout öffnen. Die Theme-Konfiguration unterstützt sowohl den Light- als auch den Dark-Modus, sodass Sie Farben, Ränder, Text, Buttons und die Randradius anpassen können.

Die clientseitige themeConfig-Option ist veraltet und wird in der nächsten Hauptversion des Checkout SDK (v2.0.0) entfernt. Ihre Übergabe protokolliert eine Veraltbarkeitswarnung in der Browserkonsole. Konfigurieren Sie Ihr Theme stattdessen beim Erstellen der Checkout-Session über die API mithilfe des Parameters customization.theme_config — siehe Anpassung des Checkout-Themes — oder visuell auf der Design-Seite im Dashboard. Für Sessions konfigurierte Themes gelten gleichermaßen für Overlay-, Inline- und gehostete Checkouts.

Dieser Abschnitt behandelt die clientseitige Konfiguration von Themes mit dem Checkout SDK, die veraltet ist. Der empfohlene Ansatz besteht darin, Themes serverseitig beim Erstellen einer Checkout-Session über die API mithilfe des Parameters theme_config zu konfigurieren. Informationen zur Konfiguration auf API-Ebene finden Sie unter Anpassung des Checkout-Themes. Alternativ können Sie Themes auf der Design-Seite im Dashboard visuell mit einer Live-Vorschau 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 im hellen Modus

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 im dunklen Modus

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

Teilweise Theme-Überschreibung

Sie können nur bestimmte Eigenschaften überschreiben. Für Eigenschaften, die Sie nicht angeben, verwendet der Checkout die Standardwerte:

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,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

TypeScript-Typen

Für TypeScript-Nutzer werden alle Typen der Theme-Konfiguration 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 stellt über das Ereignissystem detaillierte Fehlerinformationen bereit. Implementieren Sie in Ihrem onEvent-Callback stets eine ordnungsgemäße Fehlerbehandlung:

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 bei auftretenden Fehlern eine gute Benutzererfahrung zu gewährleisten.

Best Practices

Einmalige Initialisierung: Initialisieren Sie das SDK einmal beim Laden Ihrer Anwendung und nicht bei jedem Checkout-Versuch
Fehlerbehandlung: Implementieren Sie in Ihrem Event-Callback stets eine ordnungsgemäße Fehlerbehandlung
Testmodus: Verwenden Sie während der Entwicklung den test-Modus und wechseln Sie erst dann zu live, wenn Sie für den Produktionseinsatz bereit sind
Ereignisbehandlung: Behandeln Sie alle relevanten Ereignisse für eine vollständige Benutzererfahrung
Gültige URLs: Verwenden Sie stets gültige Checkout-URLs aus der API zum Erstellen einer Checkout-Session
TypeScript: Verwenden Sie TypeScript für bessere Typsicherheit und eine bessere Entwicklererfahrung
Ladezustände: Zeigen Sie Ladezustände an, während der Checkout geöffnet wird, um die UX zu verbessern
Timer-Verwaltung: Deaktivieren Sie den Timer (showTimer: false), wenn Sie den Ablauf der Session manuell behandeln möchten

Fehlerbehebung

Checkout not opening

Mögliche Ursachen:

SDK wurde vor dem Aufruf von open() nicht initialisiert
Ungültige Checkout-URL
JavaScript-Fehler in der Konsole
Probleme mit der Netzwerkverbindung

Lösungen:

Überprüfen Sie, dass die SDK-Initialisierung vor dem Öffnen des Checkouts erfolgt
Überprüfen Sie die Konsole auf Fehler
Stellen Sie sicher, dass die Checkout-URL gültig ist und aus der API zum Erstellen einer Checkout-Session stammt
Überprüfen Sie die Netzwerkverbindung

Events not firing

Mögliche Ursachen:

Event-Handler wurde nicht ordnungsgemäß eingerichtet
JavaScript-Fehler verhindern die Weitergabe von Ereignissen
SDK wurde nicht korrekt initialisiert

Lösungen:

Bestätigen Sie, dass der Event-Handler in Initialize() ordnungsgemäß konfiguriert ist
Überprüfen Sie die Browserkonsole auf JavaScript-Fehler
Überprüfen Sie, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
Testen Sie zunächst mit einem einfachen Event-Handler

Styling issues

Mögliche Ursachen:

CSS-Konflikte mit den Styles Ihrer Anwendung
Theme-Einstellungen wurden nicht korrekt angewendet
Probleme mit dem responsiven Design

Lösungen:

Überprüfen Sie die Browser-DevTools auf CSS-Konflikte
Überprüfen Sie, ob die Theme-Einstellungen korrekt sind
Testen Sie verschiedene Bildschirmgrößen
Stellen Sie sicher, dass keine z-index-Konflikte mit dem Overlay bestehen

Digitale Wallets aktivieren

Ausführliche Informationen zur Einrichtung von Google Pay und anderen digitalen Wallets finden Sie auf der Seite Digitale Wallets.

Apple Pay wird im Overlay-Checkout noch nicht unterstützt. Die Unterstützung für Apple Pay wird in Kürze verfügbar sein.

Browserunterstützung

Das Dodo Payments Checkout SDK unterstützt die folgenden Browser:

Chrome (aktuellste Version)
Firefox (aktuellste Version)
Safari (aktuellste Version)
Edge (aktuellste Version)
IE11+

Overlay- vs. Inline-Checkout

Wählen Sie den passenden Checkout-Typ für Ihren Anwendungsfall:

Funktion	Overlay-Checkout	Inline-Checkout
Integrationstiefe	Modal über der Seite	Vollständig in die Seite eingebettet
Layout-Kontrolle	Begrenzt	Vollständige Kontrolle
Branding	Von der Seite getrennt	Nahtlos
Implementierungsaufwand	Geringer	Höher
Am besten geeignet für	Schnelle Integration, bestehende Seiten	Individuelle Checkout-Seiten, Conversion-starke Abläufe

Verwenden Sie den Overlay-Checkout für eine schnellere Integration mit minimalen Änderungen an Ihren bestehenden Seiten. Verwenden Sie den Inline-Checkout, wenn Sie maximale Kontrolle über die Checkout-Erfahrung und ein nahtloses Branding wünschen.

Inline Checkout

Betten Sie den Checkout direkt in Ihre Seite ein, um vollständig integrierte Erfahrungen zu ermöglichen.

Checkout Sessions API

Erstellen Sie Checkout-Sessions, um Ihre Checkout-Erfahrungen zu ermöglichen.

Webhooks

Verarbeiten Sie Zahlungsereignisse serverseitig mit Webhooks.

Integration Guide

Vollständige Anleitung zur Integration von Dodo Payments.

Weitere Unterstützung erhalten Sie in unserer Discord-Community oder bei unserem Entwickler-Support-Team.

​Übersicht

​Demo

Interactive Demo

​Schnellstart

​Schritt-für-Schritt-Integrationsanleitung

​API-Referenz

​Konfiguration

​Initialisierungsoptionen

​Checkout-Optionen

​Methoden

​Checkout öffnen

​Checkout schließen

​Status überprüfen

​Ereignisse

​Implementierungsoptionen

​Paketmanager-Installation

​CDN-Implementierung

​Thema-Anpassung

​Grundlegende Theme-Konfiguration

​Vollständige Theme-Konfiguration

​Nur im hellen Modus

​Nur im dunklen Modus

​Teilweise Theme-Überschreibung

​Theme-Konfiguration mit anderen Optionen

​TypeScript-Typen

​Fehlerbehandlung

​Best Practices

​Fehlerbehebung

​Digitale Wallets aktivieren

​Browserunterstützung

​Overlay- vs. Inline-Checkout

​Verwandte Ressourcen

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Übersicht

Demo

Schnellstart

Schritt-für-Schritt-Integrationsanleitung

API-Referenz

Konfiguration

Initialisierungsoptionen

Checkout-Optionen

Methoden

Checkout öffnen

Checkout schließen

Status überprüfen

Ereignisse

Implementierungsoptionen

Paketmanager-Installation

CDN-Implementierung

Thema-Anpassung

Grundlegende Theme-Konfiguration

Vollständige Theme-Konfiguration

Nur im hellen Modus

Nur im dunklen Modus

Teilweise Theme-Überschreibung

Theme-Konfiguration mit anderen Optionen

TypeScript-Typen

Fehlerbehandlung

Best Practices

Fehlerbehebung

Digitale Wallets aktivieren

Browserunterstützung

Overlay- vs. Inline-Checkout

Verwandte Ressourcen