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.
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 Das Bibliotheksprodukt ist
Package.swift hinzuzufügen, fügen Sie diese Abhängigkeit hinzu:Package.swift
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 Sie können den URL-Typ auch in Xcode unter Info → URL Types hinzufügen.Verwenden Sie dieses Schema in der
Info.plist einen URL-Typ hinzu:Info.plist
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.
- SwiftUI
- SceneDelegate
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 erstelltCheckoutResult aus den Query-Parametern der Rückgabe-URL.
CheckoutStatus
erforderlich
Einer von fünf Werten:
succeeded: Die Rückgabe-URL enthältstatus=succeeded(einmalige Zahlung) oderstatus=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=processingoder ein beliebigerrequires_*-Wert), oder der Parameterstatusfehlte oder wurde nicht erkannt. Gleichen Sie sie wiecancelledab.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.result.status.
Anpassung der Darstellung
Um die Schaltfläche zum Schließen, den Präsentationsstil und das Farbschema des Sheets zu ändern, übergeben Sie einBrowserCustomization 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.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):checkoutUrlist keine gültigehttps-Checkout-Session-URL (Pfad beginnt mit/session/) aufcheckout.dodopayments.comodertest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlist 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.
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.