Ü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:Schritt-für-Schritt-Integrationsanleitung
Initialize the SDK
Initialisieren Sie das SDK in Ihrer Anwendung, typischerweise in Ihrer Hauptkomponente oder dem Einstiegspunkt der App:
Test Your Integration
- Starten Sie Ihren Entwicklungsserver:
- 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.
API-Referenz
Konfiguration
Initialisierungsoptionen
| 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
| Option | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
checkoutUrl | string | Yes | Checkout-Session-URL von der create checkout session API |
options.showTimer | boolean | No | Zeigen oder verbergen Sie den Checkout-Timer. Standardmäßig true. Wenn deaktiviert, erhalten Sie das checkout.link_expired-Ereignis, wenn die Sitzung abläuft. |
options.showSecurityBadge | boolean | No | Zeigen oder verbergen Sie das Sicherheitsabzeichen. Standardmäßig true. |
options.manualRedirect | boolean | No | Wenn aktiviert, leitet der Checkout nach Abschluss nicht automatisch weiter. Stattdessen erhalten Sie checkout.status und checkout.redirect_requested-Ereignisse, um die Weiterleitung selbst zu steuern. |
Methoden
Checkout öffnen
Öffnet das Checkout-Overlay mit der angegebenen Checkout-Sitzungs-URL.manualRedirect verwenden, behandeln Sie den Abschluss des Checkouts in Ihrem onEvent-Callback:
Kasse schließen
Schließt das Kassenoverlay programmgesteuert.Status überprüfen
Gibt an, ob das Kassenoverlay derzeit geöffnet ist.Ereignisse
Das SDK bietet Echtzeitereignisse, auf die Sie über denonEvent-Callback reagieren können:
Daten zum Kassenstatus-Ereignis
WennmanualRedirect aktiviert ist, erhalten Sie das checkout.status-Ereignis mit folgenden Daten:
Daten zum angeforderten Kassenumleitungsereignis
WennmanualRedirect aktiviert ist, erhalten Sie das checkout.redirect_requested-Ereignis mit folgenden Daten:
| Ereignistyp | Beschreibung |
|---|---|
checkout.opened | Checkout-Overlay wurde geöffnet |
checkout.form_ready | Das Checkout-Formular ist bereit, Benutzereingaben zu empfangen. Nützlich zum Ausblenden von Ladezuständen. |
checkout.payment_page_opened | Die Zahlungsseite wurde angezeigt |
checkout.customer_details_submitted | Kunden- und Rechnungsdaten wurden übermittelt |
checkout.closed | Checkout-Overlay wurde geschlossen |
checkout.redirect | Der Checkout wird eine Weiterleitung durchführen |
checkout.error | Während des Checkouts ist ein Fehler aufgetreten |
checkout.link_expired | Wird ausgelöst, wenn die Checkout-Sitzung abläuft. Wird nur empfangen, wenn showTimer auf false gesetzt ist. |
checkout.status | Wird ausgelöst, wenn manualRedirect aktiviert ist. Enthält den Checkout-Status (succeeded, failed oder processing). |
checkout.redirect_requested | Wird ausgelöst, wenn manualRedirect aktiviert ist. Enthält die URL, zu der der Kunde weitergeleitet 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:Theme-Anpassung
Sie können das Aussehen des Checkouts anpassen, indem Sie einthemeConfig-Objekt im options-Parameter übergeben, wenn Sie den Checkout öffnen. Die Theme-Konfiguration unterstützt sowohl Hell- als auch Dunkelmodus, sodass Sie Farben, Rahmen, Text, Schaltflächen und Border-Radius anpassen können.
Dieser Abschnitt behandelt die clientseitige Themenkonfiguration mithilfe des Checkout SDK. Du kannst Themen auch serverseitig konfigurieren, wenn du eine Checkout-Session über die API mit dem
theme_config-Parameter erstellst. Siehe Checkout Theme Customization für Konfiguration auf API-Ebene oder verwende die Design page im Dashboard, um Themen visuell mit Live-Vorschau zu konfigurieren.Grundlegende Theme-Konfiguration
Vollständige Theme-Konfiguration
Alle verfügbaren Theme-Eigenschaften:Nur Hellmodus
Wenn Sie nur das helle Theme anpassen möchten:Nur Dunkelmodus
Wenn Sie nur das dunkle Theme anpassen möchten:Teilweises Theme-Override
Sie können nur bestimmte Eigenschaften überschreiben. Der Checkout verwendet Standardwerte für nicht angegebene Eigenschaften:Theme-Konfiguration mit anderen Optionen
Sie können die Theme-Konfiguration mit anderen Checkout-Optionen kombinieren:TypeScript-Typen
Für TypeScript-Nutzer werden alle Theme-Konfigurationstypen exportiert:Fehlerbehandlung
Das SDK liefert detaillierte Fehlerinformationen über das Ereignissystem. Implementieren Sie stets eine ordnungsgemäße Fehlerbehandlung in IhremonEvent-Callback:
Best Practices
- Einmal initialisieren: Initialisieren Sie das SDK einmal beim Laden Ihrer Anwendung, nicht bei jedem Checkout-Versuch
- Fehlerbehandlung: Implementieren Sie stets eine ordnungsgemäße Fehlerbehandlung in Ihrem Ereignis-Callback
- Testmodus: Verwenden Sie
testwährend der Entwicklung und wechseln Sie erst zulive, wenn Sie produktionsbereit sind - Ereignisbehandlung: Verarbeiten Sie alle relevanten Ereignisse für ein vollständiges Benutzererlebnis
- Gültige URLs: Verwenden Sie immer gültige Checkout-URLs aus der Create Checkout Session API
- TypeScript: Verwenden Sie TypeScript für bessere Typensicherheit und Entwicklererfahrung
- Ladezustände: Zeigen Sie Ladezustände, während der Checkout geöffnet wird, um die UX zu verbessern
- Manuelle Weiterleitungen: Verwenden Sie
manualRedirect, wenn Sie benutzerdefinierte Kontrolle über die Navigation nach dem Checkout benötigen - Timer-Verwaltung: Deaktivieren Sie den Timer (
showTimer: false), wenn Sie den Sitzungsablauf manuell behandeln möchten
Fehlerbehebung
Checkout not opening
Checkout not opening
Mögliche Ursachen:
- SDK wurde nicht initialisiert, bevor
open()aufgerufen wurde - Ungültige Checkout-URL
- JavaScript-Fehler in der Konsole
- Netzwerkverbindungsprobleme
- Überprüfen Sie, dass das SDK initialisiert wird, bevor der Checkout geöffnet wird
- Prüfen Sie die Konsole auf Fehler
- Stellen Sie sicher, dass die Checkout-URL gültig ist und von der Create Checkout Session API stammt
- Überprüfen Sie die Netzwerkverbindung
Events not firing
Events not firing
Mögliche Ursachen:
- Ereignis-Handler nicht korrekt eingerichtet
- JavaScript-Fehler verhindern die Ereignisweiterleitung
- SDK nicht korrekt initialisiert
- Bestätigen Sie, dass der Ereignis-Handler korrekt in
Initialize()konfiguriert ist - Prüfen Sie die Browserkonsole auf JavaScript-Fehler
- Stellen Sie sicher, dass die SDK-Initialisierung erfolgreich abgeschlossen wurde
- Testen Sie zuerst mit einem einfachen Ereignis-Handler
Styling issues
Styling issues
Mögliche Ursachen:
- CSS-Konflikte mit den Styles Ihrer Anwendung
- Theme-Einstellungen wurden nicht korrekt angewendet
- Probleme mit dem Responsive Design
- Überprüfen Sie CSS-Konflikte mit den DevTools des Browsers
- Stellen Sie sicher, dass die Theme-Einstellungen korrekt sind
- Testen Sie auf verschiedenen Bildschirmgrößen
- Stellen Sie sicher, dass keine Z-Index-Konflikte mit dem Overlay bestehen
Aktivierung digitaler Wallets
Für ausführliche Informationen zur Einrichtung von Google Pay und anderen digitalen Wallets siehe die Seite Digital Wallets.Apple Pay wird im Overlay-Checkout noch nicht unterstützt. Die Unterstützung für Apple Pay kommt bald.
Browser-Unterstützung
Das Dodo Payments Checkout SDK unterstützt die folgenden Browser:- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- IE11+
Overlay- vs. Inline-Checkout
Wählen Sie den richtigen Checkout-Typ für Ihren Anwendungsfall:| Funktion | Overlay-Checkout | Inline-Checkout |
|---|---|---|
| Integrationsdichte | Modal über der Seite | Vollständig in die Seite eingebettet |
| Layout-Kontrolle | Eingeschränkt | Volle Kontrolle |
| Branding | Getrennt von der Seite | Nahtlos |
| Umsetzungsaufwand | Geringer | Höher |
| Am besten geeignet für | Schnelle Integration, bestehende Seiten | Individuelle Checkout-Seiten, konversionsstarke Abläufe |
Verwandte Ressourcen
Inline Checkout
Binden Sie den Checkout direkt in Ihre Seite ein für vollständig integrierte Erfahrungen.
Checkout Sessions API
Erstellen Sie Checkout-Sessions, um Ihre Checkout-Erlebnisse zu ermöglichen.
Webhooks
Verarbeiten Sie Zahlungsereignisse serverseitig mit Webhooks.
Integration Guide
Vollständige Anleitung zur Integration von Dodo Payments.