Overlay Checkout

Der Overlay-Checkout öffnet ein Modal-Fenster über deiner Seite. Kundinnen und Kunden geben ihre Zahlungsdaten im Modal ein, während deine Seite im Hintergrund sichtbar bleibt. Wenn sie das Modal schließen, kehrt die Steuerung zu deiner Seite zurück. Nach erfolgreicher Zahlung werden sie zu return_url weitergeleitet.

Overlay-Checkout-Modal über einer Produktseite

Interactive Demo

Sieh dir den Overlay-Checkout in unserer Live-Demo in Aktion an.

Schnellstart

Installiere das SDK, initialisiere es und öffne den Checkout mit einer Checkout-URL aus der create checkout session API:

import { DodoPayments } from "dodopayments-checkout";

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

Schrittweise Integration

Install the SDK

Installation über npm, yarn oder pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Rufe Initialize einmal beim Laden deiner App auf, normalerweise in deiner Hauptkomponente oder am Einstiegspunkt der App:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Initialisiere das SDK immer, bevor du den Checkout öffnest. Initialisiere es einmal beim Laden deiner Anwendung, nicht vor jedem Checkout-Versuch.

Create a Checkout Button

Erstelle eine Komponente, die das Checkout-Modal ö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(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.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 the Button to Your Page

Verwende die Checkout-Button-Komponente in deiner 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 Redirects

Erstelle Seiten, um Checkout-Weiterleitungen nach der Zahlung zu verarbeiten:

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

Starte deinen Entwicklungsserver:

npm run dev

Teste den Checkout-Ablauf:
- Klicke auf die Checkout-Schaltfläche
- Überprüfe, ob das Modal angezeigt wird
- Teste den Zahlungsvorgang mit Testzugangsdaten
- Bestätige, dass Weiterleitungen korrekt funktionieren

Checkout-Ereignisse sollten in der Browserkonsole protokolliert werden.

Go Live

Wenn du für den Produktivbetrieb bereit bist:

Ändere den Modus in 'live':

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

Aktualisiere deine Checkout-URLs, sodass sie Live-Checkout-Sessions aus deinem Backend verwenden
Teste den vollständigen Ablauf in der Produktionsumgebung
Überwache Ereignisse und Fehler

API-Referenz

Initialisieren

Rufe Initialize einmal auf, um das SDK einzurichten:

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

DodoPayments.Initialize(options);

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

Checkout öffnen

Öffne das Checkout-Modal:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Option	Typ	Erforderlich	Beschreibung
`checkoutUrl`	`string`	Ja	Checkout-Session-URL aus der create checkout session API
`options.showTimer`	`boolean`	Nein	Session-Timer anzeigen oder ausblenden. Standardmäßig `true`. Wenn deaktiviert, erhältst du beim Ablauf der Session das Ereignis `checkout.link_expired`.
`options.showSecurityBadge`	`boolean`	Nein	Sicherheits-Badge anzeigen oder ausblenden. Standardmäßig `true`
`options.manualRedirect`	`boolean`	Nein	Wenn `true`, automatische Weiterleitungen verhindern. Der Checkout sendet `checkout.status` mit dem Zahlungsergebnis und `checkout.redirect_requested` mit der zu öffnenden URL. Die Navigation übernimmst du selbst
`options.themeConfig`	`ThemeConfig`	Nein	Veraltet. Konfiguriere das Theme stattdessen serverseitig beim Erstellen der Checkout-Session
`options.payButtonText`	`string`	Nein	Benutzerdefinierter Text für die Zahlungsschaltfläche
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	Nein	Globale Schriftgröße für den Checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	Nein	Globale Schriftstärke für den Checkout

Checkout schließen

Schließe das Modal programmatisch:

DodoPayments.Checkout.close();

Status prüfen

Prüfe, ob das Modal derzeit geöffnet ist:

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

Ereignisse

Höre über den an Initialize übergebenen Callback onEvent auf Checkout-Ereignisse:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Ereignis	Beschreibung
`checkout.opened`	Modal wurde geöffnet
`checkout.form_ready`	Formular ist zur Eingabe bereit. Verwende dies, um Ladezustände auszublenden
`checkout.payment_page_opened`	Zahlungsseite wird angezeigt
`checkout.customer_details_submitted`	Kunden- und Rechnungsdaten wurden übermittelt
`checkout.closed`	Modal wurde geschlossen
`checkout.redirect`	Checkout wird weiterleiten, z. B. zu einer Bankseite
`checkout.error`	Während des Checkouts ist ein Fehler aufgetreten
`checkout.link_expired`	Die Checkout-Session ist abgelaufen. Wird nur empfangen, wenn `showTimer` auf `false` gesetzt ist.

CDN-Implementierung

Für eine schnelle Integration ohne Build-Schritt kannst du das SDK über CDN laden:

<!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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Theme-Anpassung

Die clientseitige Option themeConfig ist veraltet und wird in der nächsten Hauptversion des Checkout-SDKs (v2.0.0) entfernt. Bei ihrer Übergabe wird eine Warnung zur Veraltung in der Browserkonsole protokolliert. Konfiguriere dein Theme stattdessen beim Erstellen der Checkout-Session über die API mit dem Parameter customization.theme_config – siehe Checkout Theme Customization – oder visuell auf der Design page im Dashboard. Über die Session konfigurierte Themes gelten gleichermaßen für Overlay-, Inline- und Hosted-Checkout.

Dieser Abschnitt behandelt die veraltete clientseitige Theme-Konfiguration mit dem Checkout-SDK. Empfohlen wird, Themes beim Erstellen einer Checkout-Session über die API serverseitig mit dem Parameter theme_config zu konfigurieren. Informationen zur Konfiguration auf API-Ebene findest du unter Checkout Theme Customization. Alternativ kannst du Themes visuell mit Live-Vorschau auf der Design page im Dashboard konfigurieren.

Wenn du die clientseitige Theme-Konfiguration verwenden musst, übergib themeConfig im Parameter options:

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

Theme-Eigenschaften

Alle verfügbaren Theme-Eigenschaften für den hellen und dunklen Modus:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Fehlerbehandlung

Implementiere immer eine Fehlerbehandlung in deinem onEvent-Callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Verarbeite immer das Ereignis checkout.error, um bei auftretenden Fehlern eine gute Benutzererfahrung zu gewährleisten.

Best Practices

Einmalige Initialisierung: Rufe Initialize einmal beim Laden deiner App auf, nicht vor jedem Checkout
Fehlerbehandlung: Implementiere eine geeignete Fehlerbehandlung in deinem Ereignis-Callback
Testmodus: Verwende während der Entwicklung den Modus "test" und wechsle erst für den Produktivbetrieb zu "live"
Ereignisverarbeitung: Verarbeite alle relevanten Ereignisse für eine vollständige Benutzererfahrung
Gültige URLs: Verwende immer gültige Checkout-URLs aus der create checkout session API
TypeScript: Verwende TypeScript für bessere Typsicherheit und eine bessere Entwicklererfahrung
Ladezustände: Zeige während des Öffnens des Checkouts Ladezustände an, um die UX zu verbessern
Timer-Verwaltung: Deaktiviere den Timer (showTimer: false), wenn du den Ablauf der Session manuell verarbeiten möchtest

Fehlerbehebung

Events not firing

Mögliche Ursachen:

Ereignishandler wurde nicht korrekt eingerichtet
JavaScript-Fehler verhindern die Weitergabe von Ereignissen
SDK wurde nicht korrekt initialisiert

Lösungen:

Bestätige, dass der Ereignishandler in Initialize() korrekt konfiguriert ist
Prüfe die Browserkonsole auf JavaScript-Fehler
Überprüfe, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
Teste zunächst mit einem einfachen Ereignishandler

Styling issues

Mögliche Ursachen:

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

Lösungen:

Prüfe die Browser-DevTools auf CSS-Konflikte
Überprüfe, ob die Theme-Einstellungen korrekt sind
Teste verschiedene Bildschirmgrößen
Stelle sicher, dass keine z-index-Konflikte mit dem Modal bestehen

Digitale Wallets

Ausführliche Informationen zur Einrichtung von Google Pay und anderen digitalen Wallets findest du auf der Seite Digital Wallets.

Apple Pay wird im Overlay-Checkout derzeit nicht unterstützt.

Browser-Unterstützung

Das Dodo Payments Checkout-SDK unterstützt:

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

Overlay- vs. Inline-Checkout

Wähle den passenden Checkout-Typ für deinen Anwendungsfall:

Funktion	Overlay	Inline
Integrationstiefe	Modal über der Seite	Vollständig in die Seite eingebettet
Layout-Steuerung	Begrenzt	Vollständige Kontrolle
Branding	Unabhängig von der Seite	Passt zu deiner Seite
Implementierungsaufwand	Geringer	Höher
Am besten geeignet für	Schnelle Integration, bestehende Seiten	Benutzerdefinierte Checkout-Seiten, Abläufe mit hoher Conversion

Verwende den Overlay-Checkout für eine schnellere Integration mit minimalen Änderungen an deinen bestehenden Seiten. Verwende den Inline-Checkout, wenn du maximale Kontrolle über das Checkout-Erlebnis und ein einheitliches Branding möchtest.

Inline Checkout

Bette den Checkout direkt in deine Seite ein, um vollständig integrierte Erlebnisse zu ermöglichen.

Checkout Sessions API

Erstelle Checkout-Sessions für deine Checkout-Erlebnisse.

Webhooks

Verarbeite Zahlungsereignisse serverseitig mit Webhooks.

Integration Guide

Vollständige Anleitung zur Integration von Dodo Payments.

Weitere Hilfe findest du in unserer Discord-Community oder beim Developer-Support-Team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Schnellstart

Schrittweise Integration

API-Referenz

Initialisieren

Checkout öffnen

Checkout schließen

Status prüfen

Ereignisse

CDN-Implementierung

Theme-Anpassung

Theme-Eigenschaften

Fehlerbehandlung

Best Practices

Fehlerbehebung

Digitale Wallets

Browser-Unterstützung

Overlay- vs. Inline-Checkout

Verwandte Ressourcen

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Schnellstart

​Schrittweise Integration

​API-Referenz

​Initialisieren

​Checkout öffnen

​Checkout schließen

​Status prüfen

​Ereignisse

​CDN-Implementierung

​Theme-Anpassung

​Theme-Eigenschaften

​Fehlerbehandlung

​Best Practices

​Fehlerbehebung

​Digitale Wallets

​Browser-Unterstützung

​Overlay- vs. Inline-Checkout

​Verwandte Ressourcen

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Schnellstart

Schrittweise Integration

API-Referenz

Initialisieren

Checkout öffnen

Checkout schließen

Status prüfen

Ereignisse

CDN-Implementierung

Theme-Anpassung

Theme-Eigenschaften

Fehlerbehandlung

Best Practices

Fehlerbehebung

Digitale Wallets

Browser-Unterstützung

Overlay- vs. Inline-Checkout

Verwandte Ressourcen