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.

Dieser Abschnitt behandelt die clientseitige Theme-Konfiguration mit dem Checkout SDK. Sie können Themes auch serverseitig konfigurieren, wenn Sie eine Checkout-Sitzung über die API mithilfe des theme_config-Parameters erstellen. Siehe Checkout-Thema-Anpassung für API-Level-Konfiguration oder verwenden Sie die Gestaltungsseite im Dashboard, um Themes visuell mit Live-Vorschau zu konfigurieren.

Grundlegende Thema-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 Thema-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 Light-Modus

Wenn Sie nur das Light-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 Dark-Modus

Wenn Sie nur das Dark-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 Thema-Überschreibung

Sie können nur bestimmte Eigenschaften überschreiben. Das 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
    },
  },
});

Thema-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-Benutzer 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 bietet detaillierte Fehlerinformationen ü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 bei Auftreten von Fehlern zu bieten.

Best Practices

Einmal initialisieren: Initialisieren Sie das SDK einmal, wenn Ihre Anwendung geladen wird, nicht bei jedem Checkout-Versuch
Fehlerbehandlung: Implementieren Sie immer eine ordnungsgemäße Fehlerbehandlung in Ihrem Ereignis-Callback
Testmodus: Verwenden Sie test-Modus während der Entwicklung und wechseln Sie zu live nur, wenn Sie für die Produktion bereit sind
Ereignisbehandlung: Behandeln Sie alle relevanten Ereignisse für ein vollständiges Benutzererlebnis
Gültige URLs: Verwenden Sie immer gültige Checkout-URLs von der Checkout-Session-API erstellen
TypeScript: Verwenden Sie TypeScript für bessere Typsicherheit und Entwicklererfahrung
Ladezustände: Zeigen Sie Ladezustände an, während das Checkout geöffnet wird, um die UX zu verbessern
Timer-Management: Deaktivieren Sie den Timer (showTimer: false), wenn Sie die Sitzungsexpiration manuell durchführen möchten

Fehlerbehebung

Checkout not opening

Mögliche Ursachen:

SDK nicht initialisiert, bevor open() aufgerufen wird
Ungültige Checkout-URL
JavaScript-Fehler in der Konsole
Netzwerkverbindungsprobleme

Lösungen:

Stellen Sie sicher, dass die SDK-Initialisierung vor dem Öffnen des Checkouts erfolgt
Überprüfen Sie Konsolenfehler
Stellen Sie sicher, dass die Checkout-URL gültig ist und von der Checkout-Session-API erstellt wurde
Überprüfen Sie die Netzwerkverbindung

Events not firing

Mögliche Ursachen:

Ereignis-Handler nicht richtig eingerichtet
JavaScript-Fehler verhindern die Ereignisausbreitung
SDK nicht korrekt initialisiert

Lösungen:

Bestätigen Sie, dass der Ereignis-Handler richtig im Initialize() konfiguriert ist
Überprüfen Sie die Browser-Konsole auf JavaScript-Fehler
Verifizieren Sie, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
Testen Sie zuerst mit einem einfachen Ereignis-Handler

Styling issues

Mögliche Ursachen:

CSS-Konflikte mit Ihren Anwendungsstilen
Thema-Einstellungen nicht korrekt angewendet
Probleme mit dem responsiven Design

Lösungen:

Überprüfen Sie auf CSS-Konflikte in den Entwicklertools des Browsers
Verifizieren Sie, dass die Thema-Einstellungen korrekt sind
Testen Sie auf verschiedenen Bildschirmgrößen
Stellen Sie sicher, dass keine z-Index-Konflikte mit dem Overlay bestehen

Digitale Geldbörsen aktivieren

Für detaillierte Informationen zum Einrichten von Google Pay und anderen digitalen Geldbörsen siehe die Seite Digitale Geldbörsen.

Apple Pay wird im Overlay-Checkout noch nicht unterstützt. Unterstützung für Apple Pay kommt bald.

Browser-Unterstützung

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

Chrome (neueste)
Firefox (neueste)
Safari (neueste)
Edge (neueste)
IE11+

Overlay- vs Inline-Checkout

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

Funktion	Overlay-Checkout	Inline-Checkout
Integrationsgrad	Modal über der Seite	Vollständig in die Seite integriert
Layoutkontrolle	Begrenzt	Volle Kontrolle
Branding	Getrennt von der Seite	Nahtlos
Implementierungsaufwand	Geringer	Höher
Beste für	Schnelle Integration, bestehende Seiten	Benutzerdefinierte Checkout-Seiten, hochkonvertierende Flows

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.

Inline Checkout

Binden Sie das Checkout direkt in Ihre Seite ein für vollständig integrierte Erlebnisse.

Checkout Sessions API

Erstellen Sie Checkout-Sitzungen, um Ihre Checkout-Erlebnisse zu unterstützen.

Webhooks

Zahlungsereignisse serverseitig mit Webhooks behandeln.

Integration Guide

Vollständiger Leitfaden zur Integration von Dodo Payments.

Für weitere Hilfe besuchen Sie unsere Discord-Community oder kontaktieren Sie unser 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 Thema-Konfiguration

​Vollständige Thema-Konfiguration

​Nur Light-Modus

​Nur Dark-Modus

​Teilweise Thema-Überschreibung

​Thema-Konfiguration mit anderen Optionen

​TypeScript-Typen

​Fehlerbehandlung

​Best Practices

​Fehlerbehebung

​Digitale Geldbörsen aktivieren

​Browser-Unterstü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 Thema-Konfiguration

Vollständige Thema-Konfiguration

Nur Light-Modus

Nur Dark-Modus

Teilweise Thema-Überschreibung

Thema-Konfiguration mit anderen Optionen

TypeScript-Typen

Fehlerbehandlung

Best Practices

Fehlerbehebung

Digitale Geldbörsen aktivieren

Browser-Unterstützung

Overlay- vs Inline-Checkout

Verwandte Ressourcen