Skip to main content
Diese Seite behandelt das offizielle iOS-Checkout-SDK von Dodo Payments für Swift. Es öffnet den gehosteten Checkout von Dodo Payments in einer nativen Browseransicht und gibt ein typisiertes Ergebnis zurück.

Checkout Sessions API

Erstellen Sie das checkout_url, das dieses SDK öffnet, in Ihrem Backend.

Mobile Integration Guide

Erfahren Sie, wie dieses SDK in den vollständigen mobilen Zahlungsablauf passt.
Das iOS SDK öffnet den gehosteten Checkout von Dodo Payments in SFSafariViewController und gibt ein typisiertes CheckoutResult zurück, wenn der Kunde den Checkout abschließt oder verlässt. Es enthält keinen API-Schlüssel und keinen Netzwerkcode und ruft daher niemals die Dodo Payments API auf. Der Checkout läuft in der Browseransicht. Das SDK zeigt diese Ansicht an und schließt sie und liest das Ergebnis aus der Rückgabe-URL. Voraussetzungen: iOS 16 oder höher sowie Swift 6.2 oder höher (das Paket deklariert swift-tools-version: 6.2). Das SDK hat keine Abhängigkeiten von Drittanbietern.

Installation

1

Add the Package

Gehen Sie in Xcode zu File → Add Package Dependencies und geben Sie die Paket-URL ein:
Wählen Sie Version 1.1.0 oder höher. Anpassung der Darstellung erfordert 1.1.0.Um das Paket stattdessen in Package.swift hinzuzufügen, fügen Sie diese Abhängigkeit hinzu:
Package.swift
Das Bibliotheksprodukt ist DodoCheckout.
2

Register a Callback URL Scheme

Registrieren Sie ein URL-Schema, damit iOS die Rückgabe-URL des Checkouts zurück an Ihre App weiterleitet. Fügen Sie Ihrem Info.plist einen URL-Typ hinzu:
Info.plist
Sie können den URL-Typ auch in Xcode unter Info → URL Types hinzufügen.Verwenden Sie dieses Schema in der returnUrl, die Sie an das SDK übergeben, zum Beispiel myapp://checkout/return, und setzen Sie dieselbe URL als return_url der Checkout-Session, wenn Ihr Backend die Session erstellt. Das SDK gleicht die Rückgabe-URL anhand von Schema, Host und Pfad ab. Die URL muss keine echte Seite laden.

Verwendung

DodoCheckout.start ist eine async-Funktion, die auf dem Main Actor ausgeführt wird. Übergeben Sie checkoutUrl als URL, die aus dem checkout_url erstellt wurde, das Ihr Backend zurückgibt:
onEvent empfängt die Ereignisse .opened, .returnReceived und .closed. Ihre name-Werte sind checkout.opened, checkout.return_received und checkout.closed. Verwenden Sie Ereignisse nur für die Protokollierung und niemals, um das Ergebnis zu bestimmen.

Weiterleiten der Rückgabe-URL

SFSafariViewController kann seine eigene Rückgabe-URL nicht abfangen, daher öffnet iOS die URL stattdessen in Ihrer App. Leiten Sie jede eingehende URL an DodoCheckout.handleOpenURL(_:) weiter. Rufen Sie es in einer App ohne Scenes aus dem application(_:open:options:) Ihres App-Delegates auf.
Sie können jede URL weiterleiten. handleOpenURL wird nur bei einer URL aktiv, die mit der returnUrl des laufenden Checkouts übereinstimmt, und gibt dafür true zurück. Für jede andere URL gibt es false zurück. Behandeln Sie diese URL daher selbst.

Bedeutung des Ergebnisses

Das SDK erstellt CheckoutResult aus den Query-Parametern der Rückgabe-URL.
result.status ist ein UI-Hinweis und kein Zahlungsnachweis. Bestätigen Sie jede Zahlung von Ihrem Backend aus mit dem payment.succeeded- oder subscription.active-Webhook.
CheckoutStatus
erforderlich
Einer von fünf Werten:
  • succeeded: Die Rückgabe-URL enthält status=succeeded (einmalige Zahlung) oder status=active (Subscription).
  • failed: Die Zahlung wurde abgelehnt (status=failed).
  • cancelled: Der Kunde hat das Sheet geschlossen, bevor die Rückgabe-URL eingetroffen ist. Das SDK kennt das Ergebnis nicht, und die Zahlung könnte erfolgreich gewesen sein. Zeigen Sie daher keinen Fehlerbildschirm an. Gleichen Sie stattdessen die abandoned session ab.
  • pending: Die Zahlung wird später abgeschlossen (status=processing oder ein beliebiger requires_*-Wert), oder der Parameter status fehlte oder wurde nicht erkannt. Gleichen Sie sie wie cancelled ab.
  • expired: Die Checkout-Session ist abgelaufen (status=expired).
String?
Der Query-Parameter payment_id, sofern die Rückgabe-URL einen solchen enthält. Zeigen Sie ihn in Ihrer UI an, verwenden Sie ihn jedoch nicht zur Zugriffserteilung. Siehe Zahlung verifizieren.
String?
Der Query-Parameter subscription_id. Wird für Subscription-Checkouts gesetzt.
[String]?
Der Query-Parameter license_key. Wird gesetzt, wenn der Checkout Produkte mit Lizenzschlüsseln enthält.
String?
Der Query-Parameter email. Wird gesetzt, wenn der Checkout eine E-Mail-Adresse erfasst.
[String: String]
Jeder Query-Parameter aus der Rückgabe-URL unverändert.

Zahlung verifizieren

Webhooks

Dodo Payments ruft Ihr Backend auf, wenn eine Zahlung erfolgreich ist oder eine Subscription aktiviert wird.

Get Payment Detail

Suchen Sie paymentId mit Ihrem geheimen Schlüssel ab, um den Status zu prüfen.
Erteilen Sie den Zugriff erst, nachdem eine dieser Möglichkeiten die Zahlung bestätigt hat. Verlassen Sie sich nicht allein auf result.status.

Anpassung der Darstellung

Um die Schaltfläche zum Schließen, den Präsentationsstil und das Farbschema des Sheets zu ändern, übergeben Sie ein BrowserCustomization als customization an start(...). Jedes Feld ist optional. Bei einem nil-Feld setzt das SDK diese Option nicht, und iOS verwendet seinen eigenen Standardwert. Die Ausnahme ist presentationStyle: Dort bedeutet nil pageSheet.
DismissButtonStyle?
Stil der Schaltfläche zum Schließen: done, close oder cancel. iOS entscheidet, ob sie als Bezeichnung oder Symbol dargestellt wird.
PresentationStyle?
pageSheet (der Standardwert) zeigt eine Karte an, die der Kunde zum Schließen nach unten wischen kann. fullScreen bedeckt den gesamten Bildschirm und verfügt über keine Geste zum Schließen.
Bool?
Ermöglicht das Ausblenden der Symbolleiste beim Scrollen der Seite. Dies ist nur wirksam, wenn presentationStyle den Wert fullScreen hat. Bei pageSheet bleiben die Leisten unabhängig von dieser Einstellung fixiert.
ColorScheme?
light oder dark erzwingt diese Darstellung unabhängig von der Systemeinstellung des Geräts. system folgt der Systemeinstellung. Diese Option gestaltet nur die nativen Steuerelemente um die Seite herum. Der helle oder dunkle Modus der Checkout-Seite selbst stammt aus customization.theme der Checkout-Session, und ihre Farben stammen aus customization.theme_config.
iOS bietet keine Option für die Farbe der Symbolleiste. Die zugrunde liegenden Tint-Eigenschaften von SFSafariViewController sind seit iOS 26 veraltet.

Fehler

start löst CheckoutError nur bei falscher Verwendung oder einem Plattformfehler aus. Lesen Sie den Grund aus error.code. Das Abbrechen durch einen Kunden oder eine abgelehnte Zahlung ist immer ein Ergebnis und niemals ein ausgelöster Fehler.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl ist keine gültige https-Checkout-Session-URL (Pfad beginnt mit /session/) auf checkout.dodopayments.com oder test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl ist keine absolute URL mit einem Schema und einem Host.
  • alreadyInProgress (ALREADY_IN_PROGRESS): Ein anderer Checkout läuft bereits. Es kann immer nur ein Checkout gleichzeitig ausgeführt werden.
  • platformError (PLATFORM_ERROR): Ein unerwarteter Plattformfehler, z. B. kein View Controller, von dem aus die Ansicht dargestellt werden kann.
Prüfen Sie nach einem ausgelösten Fehler ebenfalls auf eine verlassene Session. Wenn das Sheet nicht bestätigt hat, dass es angezeigt wurde, behält das SDK die Session im Datensatz, da der Checkout möglicherweise noch geöffnet ist. Die Ausnahme ist alreadyInProgress: Ein dann gefundener Datensatz gehört zu dem Checkout, der noch läuft.

Verlassene Sessions

Das SDK zeichnet die Checkout-Session auf, wenn es den Checkout anzeigt, und löscht den Datensatz nur, wenn der Checkout mit succeeded, failed oder expired endet. Der Datensatz bleibt bestehen, wenn die App während des Checkouts beendet wird sowie nach einem Ergebnis von cancelled oder pending. Prüfen Sie beim nächsten Start und nach jedem Ergebnis von cancelled oder pending danach.
abandoned.sessionId ist die ID der Checkout-Session, die mit cks_ beginnt. abandoned.createdAt ist der Zeitpunkt, zu dem der Date-Checkout gestartet wurde. Ihr Backend kann die Session mit Get Checkout Session abrufen. Dabei werden payment_id und payment_status zurückgegeben. Behandeln Sie die Zahlung, bis sie einen endgültigen Status erreicht, als ausstehend und nicht als fehlgeschlagen.

Verwandte Inhalte

Mobile Integration Guide

Derselbe Vertrag für Android, React Native und Flutter.

React Native SDK

Bindet denselben Swift-Kern unter iOS ein.
Zuletzt geändert am 26. September 2026