Overlay Checkout

Ü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

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

SDK installieren

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

npm install dodopayments-checkout

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.

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

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

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

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

Live gehen

Wenn Sie bereit für die Produktion sind:

Ändern Sie den Modus auf '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"`	Ja	Umgebungsmodus: `'test'` für die Entwicklung, `'live'` für die Produktion
`displayType`	`"overlay" \| "inline"`	Nein	Anzeigetyp: `'overlay'` für modale Kasse (Standard), `'inline'` für eingebettete Kasse
`onEvent`	`function`	Ja	Callback-Funktion zur Verarbeitung von Kassenereignissen

Checkout-Optionen

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

Option	Typ	Erforderlich	Beschreibung
`checkoutUrl`	`string`	Ja	URL der Checkout-Sitzung von der API zur Erstellung von Checkout-Sitzungen
`options.showTimer`	`boolean`	Nein	Zeigen oder verbergen Sie den Checkout-Timer. Standardmäßig auf `true`. Wenn deaktiviert, erhalten Sie das `checkout.link_expired` Ereignis, wenn die Sitzung abläuft.
`options.showSecurityBadge`	`boolean`	Nein	Zeigen oder verbergen Sie das Sicherheitsabzeichen. Standardmäßig auf `true`.
`options.manualRedirect`	`boolean`	Nein	Wenn aktiviert, wird die Kasse 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 Abschluss der Kasse 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 Echtzeitevents, 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;
    }
  }
});

Ereignistyp	Beschreibung
`checkout.opened`	Kassenoverlay wurde geöffnet
`checkout.payment_page_opened`	Zahlungsseite wurde angezeigt
`checkout.customer_details_submitted`	Kunden- und Rechnungsdetails wurden übermittelt
`checkout.closed`	Kassenoverlay wurde geschlossen
`checkout.redirect`	Kasse wird eine Umleitung durchführen
`checkout.error`	Ein Fehler ist während der Kasse aufgetreten
`checkout.link_expired`	Wird ausgelöst, wenn die Kassen-Sitzung abläuft. Nur erhalten, wenn `showTimer` auf `false` gesetzt ist.
`checkout.status`	Wird ausgelöst, wenn `manualRedirect` aktiviert ist. Enthält den Kassenstatus (`succeeded`, `failed` oder `processing`).
`checkout.redirect_requested`	Wird 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>

TypeScript-Unterstützung

Das SDK ist in TypeScript geschrieben und enthält umfassende Typdefinitionen. Alle öffentlichen APIs sind vollständig typisiert, um die Entwicklererfahrung und IntelliSense-Unterstützung zu verbessern.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

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

Einmal initialisieren: Initialisieren Sie das SDK einmal, wenn Ihre Anwendung geladen wird, nicht bei jedem Kassenversuch.
Fehlerbehandlung: Implementieren Sie immer eine ordnungsgemäße Fehlerbehandlung in Ihrem Ereignis-Callback.
Testmodus: Verwenden Sie den test Modus während der Entwicklung und wechseln Sie erst in den live Modus, wenn Sie bereit für die Produktion sind.
Ereignisbehandlung: Behandeln Sie alle relevanten Ereignisse für eine vollständige Benutzererfahrung.
Gültige URLs: Verwenden Sie immer gültige Checkout-URLs von der API zur Erstellung von Checkout-Sitzungen.
TypeScript: Verwenden Sie TypeScript für bessere Typensicherheit und Entwicklererfahrung.
Ladezustände: Zeigen Sie Ladezustände an, während die Kasse geöffnet wird, um die Benutzererfahrung zu verbessern.
Manuelle Umleitungen: Verwenden Sie manualRedirect, wenn Sie eine benutzerdefinierte Kontrolle über die Navigation nach der Kasse benötigen.
Timer-Management: Deaktivieren Sie den Timer (showTimer: false), wenn Sie die Sitzungsablauf manuell verwalten möchten.

Fehlersuche

Kasse öffnet sich nicht

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 der Kasse erfolgt.
Überprüfen Sie auf Konsolenfehler.
Stellen Sie sicher, dass die Checkout-URL gültig und von der API zur Erstellung von Checkout-Sitzungen stammt.
Überprüfen Sie die Netzwerkverbindung.

Ereignisse werden nicht ausgelöst

Mögliche Ursachen:

Ereignishandler nicht richtig eingerichtet.
JavaScript-Fehler verhindern die Ereignisweiterleitung.
SDK nicht korrekt initialisiert.

Lösungen:

Bestätigen Sie, dass der Ereignishandler in Initialize() richtig konfiguriert ist.
Überprüfen Sie die Browserkonsole auf JavaScript-Fehler.
Stellen Sie sicher, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde.
Testen Sie zunächst mit einem einfachen Ereignishandler.

Styling-Probleme

Mögliche Ursachen:

CSS-Konflikte mit Ihren Anwendungsstilen.
Theme-Einstellungen wurden nicht korrekt angewendet.
Probleme mit dem responsiven Design.

Lösungen:

Überprüfen Sie auf CSS-Konflikte in den DevTools des Browsers.
Stellen Sie sicher, dass die Theme-Einstellungen korrekt sind.
Testen Sie auf verschiedenen Bildschirmgrößen.
Stellen Sie sicher, dass es keine z-index-Konflikte mit dem Overlay gibt.

Apple Pay aktivieren

Apple Pay ermöglicht es Kunden, Zahlungen schnell und sicher mit ihren gespeicherten Zahlungsmethoden abzuschließen. Wenn aktiviert, können Kunden das Apple Pay-Modul direkt aus dem Kassenoverlay auf unterstützten Geräten starten.

Apple Pay wird auf iOS 17+, iPadOS 17+ und Safari 17+ auf macOS unterstützt.

Um Apple Pay für Ihre Domain in der Produktion zu aktivieren, befolgen Sie diese Schritte:

Laden Sie die Apple Pay-Domain-Zuordnungsdatei herunter und laden Sie sie hoch

Laden Sie die Apple Pay-Domain-Zuordnungsdatei herunter.Laden Sie die Datei auf Ihren Webserver unter /.well-known/apple-developer-merchantid-domain-association hoch. Wenn Ihre Website beispielsweise example.com ist, stellen Sie die Datei unter https://example.com/well-known/apple-developer-merchantid-domain-association zur Verfügung.

Fordern Sie die Aktivierung von Apple Pay an

E-Mail [email protected] mit den folgenden Informationen:

Ihre Produktionsdomain-URL (z. B. https://example.com)
Anfrage zur Aktivierung von Apple Pay für Ihre Domain

Sie erhalten innerhalb von 1-2 Werktagen eine Bestätigung, sobald Apple Pay für Ihre Domain aktiviert wurde.

Überprüfen Sie die Verfügbarkeit von Apple Pay

Nach Erhalt der Bestätigung testen Sie Apple Pay in Ihrer Kasse:

Öffnen Sie Ihre Kasse auf einem unterstützten Gerät (iOS 17+, iPadOS 17+ oder Safari 17+ auf macOS)
Überprüfen Sie, ob die Apple Pay-Schaltfläche als Zahlungsoption angezeigt wird
Testen Sie den vollständigen Zahlungsablauf

Apple Pay muss für Ihre Domain aktiviert sein, bevor es als Zahlungsoption in der Produktion angezeigt wird. Kontaktieren Sie den Support, bevor Sie live gehen, wenn Sie Apple Pay anbieten möchten.

Browserunterstü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ählen Sie den richtigen Kassetyp für Ihren Anwendungsfall:

Funktion	Overlay-Checkout	Inline-Checkout
Integrationsgrad	Modal über der Seite	Vollständig in die Seite eingebettet
Layoutkontrolle	Eingeschränkt	Volle Kontrolle
Branding	Getrennt von der Seite	Nahtlos
Implementierungsaufwand	Niedriger	Höher
Am besten geeignet für	Schnelle Integration, bestehende Seiten	Benutzerdefinierte Checkout-Seiten, hochkonvertierende 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.

Inline Checkout

Betten Sie die Kasse direkt in Ihre Seite ein, um vollständig integrierte Erlebnisse zu schaffen.

Checkout Sessions API

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

Webhooks

Verarbeiten Sie Zahlungsereignisse serverseitig mit Webhooks.

Integrationsleitfaden

Vollständiger Leitfaden zur Integration von Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Übersicht

Demo

Interaktive Demo

Schnellstart

Schritt-für-Schritt-Integrationsanleitung

API-Referenz

Konfiguration

Initialisierungsoptionen

Checkout-Optionen

Methoden

Checkout öffnen

Kasse schließen

Status überprüfen

Ereignisse

Daten zum Kassenstatus-Ereignis

Daten zum angeforderten Kassenumleitungsereignis

Implementierungsoptionen

Installation über Paketmanager

CDN-Implementierung

TypeScript-Unterstützung

Fehlerbehandlung

Best Practices

Fehlersuche

Apple Pay aktivieren

Browserunterstützung

Overlay vs Inline Checkout

Verwandte Ressourcen

Inline Checkout

Checkout Sessions API

Webhooks

Integrationsleitfaden

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Übersicht

​Demo

Interaktive Demo

​Schnellstart

​Schritt-für-Schritt-Integrationsanleitung

​API-Referenz

​Konfiguration

​Initialisierungsoptionen

​Checkout-Optionen

​Methoden

​Checkout öffnen

​Kasse schließen

​Status überprüfen

​Ereignisse

​Daten zum Kassenstatus-Ereignis

​Daten zum angeforderten Kassenumleitungsereignis

​Implementierungsoptionen

​Installation über Paketmanager

​CDN-Implementierung

​TypeScript-Unterstützung

​Fehlerbehandlung

​Best Practices

​Fehlersuche

​Apple Pay aktivieren

​Browserunterstützung

​Overlay vs Inline Checkout

​Verwandte Ressourcen

Inline Checkout

Checkout Sessions API

Webhooks

Integrationsleitfaden

Übersicht

Demo

Schnellstart

Schritt-für-Schritt-Integrationsanleitung

API-Referenz

Konfiguration

Initialisierungsoptionen

Checkout-Optionen

Methoden

Checkout öffnen

Kasse schließen

Status überprüfen

Ereignisse

Daten zum Kassenstatus-Ereignis

Daten zum angeforderten Kassenumleitungsereignis

Implementierungsoptionen

Installation über Paketmanager

CDN-Implementierung

TypeScript-Unterstützung

Fehlerbehandlung

Best Practices

Fehlersuche

Apple Pay aktivieren

Browserunterstützung

Overlay vs Inline Checkout

Verwandte Ressourcen