Skip to main content
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.
L’SDK iOS apre il checkout ospitato di Dodo Payments in 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 Package.swift, aggiungi questa dipendenza:
Package.swift
Il prodotto della libreria è 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 Info.plist:
Info.plist
Puoi anche aggiungere il tipo URL in Xcode, alla voce Info → URL Types.Usa questo schema nel 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.
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 costruisce CheckoutResult a partire dai parametri di query dell’URL di ritorno.
result.status è un suggerimento per l’interfaccia, non una prova del pagamento. Conferma ogni pagamento dal backend, con il webhook payment.succeeded o subscription.active.
CheckoutStatus
obbligatorio
Uno di cinque valori:
  • succeeded: l’URL di ritorno contiene status=succeeded (pagamento una tantum) o status=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=processing o qualsiasi valore requires_*), oppure il parametro status era mancante o non riconosciuto. Riconcilialo come cancelled.
  • 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.
Concedi l’accesso solo dopo che uno di questi elementi ha confermato il pagamento. Non fare affidamento solo su result.status.

Personalizzazione dell’aspetto

Per modificare il pulsante di chiusura del foglio, lo stile di presentazione e lo schema di colori, passa un BrowserCustomization 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.
iOS non dispone di un’opzione per il colore della toolbar. Le proprietà tint sottostanti di 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): checkoutUrl non è un URL di sessione di checkout https (percorso che inizia con /session/) su checkout.dodopayments.com o test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl non è 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.
Dopo un errore generato, verifica anche la presenza di una sessione abbandonata. Se il foglio non ha confermato di essere apparso, l’SDK conserva la sessione perché il checkout potrebbe essere ancora aperto. L’eccezione è 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.
Ultima modifica il 26 settembre 2026