Questa pagina illustra l’SDK ufficiale di checkout per iOS di Dodo Payments per Swift. Apre il checkout ospitato di Dodo Payments in una vista browser nativa e restituisce un risultato tipizzato.
Checkout Sessions API
Crea il
checkout_url che questo SDK apre, dal tuo backend.Mobile Integration Guide
Scopri come questo SDK si inserisce nel flusso di pagamento mobile completo.
SFSafariViewController e restituisce un CheckoutResult tipizzato quando il cliente termina o abbandona il checkout. Non contiene alcuna API key né codice di networking, quindi non chiama mai l’API di Dodo Payments. Il checkout viene eseguito nella vista browser. L’SDK presenta e chiude questa vista e legge il risultato dall’URL di ritorno.
Requisiti: iOS 16 o versione successiva e Swift 6.2 o versione successiva (il package dichiara swift-tools-version: 6.2). L’SDK non ha dipendenze di terze parti.
Installazione
1
Add the Package
In Xcode, vai a File → Add Package Dependencies e inserisci l’URL del package:Seleziona la versione 1.1.0 o successiva. La personalizzazione dell’aspetto richiede la versione 1.1.0.Per aggiungere invece il package in Il prodotto della libreria è
Package.swift, aggiungi questa dipendenza:Package.swift
DodoCheckout.2
Register a Callback URL Scheme
Registra uno schema URL affinché iOS reindirizzi l’URL di ritorno del checkout alla tua app. Aggiungi un tipo URL al tuo Puoi anche aggiungere il tipo URL in Xcode, alla voce Info → URL Types.Usa questo schema nel
Info.plist:Info.plist
returnUrl che passi all’SDK, ad esempio myapp://checkout/return, e imposta lo stesso URL come return_url della sessione di checkout quando il backend crea la sessione. L’SDK confronta l’URL di ritorno in base a schema, host e path. Non è necessario che l’URL carichi una pagina reale.Utilizzo
DodoCheckout.start è una funzione async che viene eseguita sull’attore principale. Passa checkoutUrl come URL creato a partire dal checkout_url restituito dal tuo backend:
onEvent riceve gli eventi .opened, .returnReceived e .closed. I relativi valori name sono checkout.opened, checkout.return_received e checkout.closed. Usa gli eventi solo per il logging, mai per determinare l’esito.
Inoltro dell’URL di ritorno
SFSafariViewController non può intercettare il proprio URL di ritorno, quindi iOS apre l’URL nella tua app. Inoltra ogni URL in arrivo a DodoCheckout.handleOpenURL(_:). In un’app senza scene, chiamalo dal application(_:open:options:) del delegate dell’app.
- SwiftUI
- SceneDelegate
Puoi inoltrare ogni URL.
handleOpenURL agisce solo su un URL che corrisponde al returnUrl del checkout in corso e restituisce true per quell’URL. Per qualsiasi altro URL, restituisce false, quindi gestisci tu quell’URL.Significato del risultato
L’SDK costruisceCheckoutResult a partire dai parametri di query dell’URL di ritorno.
CheckoutStatus
obbligatorio
Uno di cinque valori:
succeeded: l’URL di ritorno contienestatus=succeeded(pagamento una tantum) ostatus=active(abbonamento).failed: il pagamento è stato rifiutato (status=failed).cancelled: il cliente ha chiuso il foglio prima che arrivasse l’URL di ritorno. L’SDK non conosce l’esito e il pagamento potrebbe essere andato a buon fine, quindi non mostrare una schermata di errore. Riconcilia invece la sessione abbandonata.pending: il pagamento viene finalizzato in seguito (status=processingo qualsiasi valorerequires_*), oppure il parametrostatusera mancante o non riconosciuto. Riconcilialo comecancelled.expired: la sessione di checkout è scaduta (status=expired).
String?
Il parametro di query
payment_id, quando l’URL di ritorno ne include uno. Mostralo nella tua interfaccia, ma non usarlo per concedere l’accesso. Consulta Verifica il pagamento.String?
Il parametro di query
subscription_id. Impostato per i checkout di abbonamenti.[String]?
Il parametro di query
license_key. Impostato quando il checkout include prodotti con license key.String?
Il parametro di query
email. Impostato quando il checkout acquisisce un indirizzo email.[String: String]
Ogni parametro di query dell’URL di ritorno, alla lettera.
Verifica il pagamento
Webhooks
Dodo Payments chiama il tuo backend quando un pagamento va a buon fine o un abbonamento viene attivato.
Get Payment Detail
Cerca
paymentId con la tua secret key per verificarne lo stato.result.status.
Personalizzazione dell’aspetto
Per modificare il pulsante di chiusura del foglio, lo stile di presentazione e lo schema di colori, passa unBrowserCustomization come customization a start(...). Ogni campo è facoltativo. Per un campo nil, l’SDK non imposta quell’opzione e iOS applica il proprio valore predefinito. L’eccezione è presentationStyle, dove nil significa pageSheet.
DismissButtonStyle?
Stile del pulsante di chiusura:
done, close o cancel. È iOS a decidere se visualizzarlo come etichetta o icona.PresentationStyle?
pageSheet (il valore predefinito) presenta una card che il cliente può chiudere scorrendo verso il basso. fullScreen occupa l’intero schermo e non dispone di un gesto di chiusura.Bool?
Consente alla toolbar di comprimersi mentre la pagina scorre. Ha effetto visibile solo quando
presentationStyle è fullScreen. Con pageSheet, le barre rimangono fisse indipendentemente da questa impostazione.ColorScheme?
light o dark forza quell’aspetto indipendentemente dall’impostazione di sistema del dispositivo. system segue l’impostazione di sistema. Questa opzione applica il tema solo ai controlli nativi intorno alla pagina. La modalità chiara o scura della pagina di checkout dipende da customization.theme nella sessione di checkout, mentre i colori dipendono da customization.theme_config.SFSafariViewController sono deprecate a partire da iOS 26.
Errori
start genera CheckoutError solo in caso di utilizzo errato o di un errore della piattaforma. Leggi il motivo da error.code. Un cliente che annulla o un pagamento rifiutato è sempre un risultato, mai un errore generato.
invalidCheckoutUrl(INVALID_CHECKOUT_URL):checkoutUrlnon è un URL di sessione di checkouthttps(percorso che inizia con/session/) sucheckout.dodopayments.comotest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlnon è un URL assoluto con schema e host.alreadyInProgress(ALREADY_IN_PROGRESS): è in esecuzione un altro checkout. È possibile eseguire un solo checkout alla volta.platformError(PLATFORM_ERROR): un errore imprevisto della piattaforma, ad esempio l’assenza di un view controller da cui effettuare la presentazione.
alreadyInProgress: il record trovato appartiene al checkout ancora in esecuzione.
Sessioni abbandonate
L’SDK registra la sessione di checkout quando presenta il checkout e cancella il record solo quando il checkout termina con
succeeded, failed o expired. Il record rimane quando l’app viene terminata durante il checkout e dopo un risultato cancelled o pending. Verificalo al successivo avvio e dopo ogni risultato cancelled o pending.abandoned.sessionId è l’ID della sessione di checkout, che inizia con cks_. abandoned.createdAt è il checkout Date avviato. Il backend può cercare la sessione con Get Checkout Session, che restituisce payment_id e payment_status. Finché il pagamento non raggiunge uno stato finale, consideralo in sospeso, non fallito.
Correlati
Mobile Integration Guide
Lo stesso contratto per Android, React Native e Flutter.
React Native SDK
Esegue il wrapping dello stesso core Swift su iOS.