Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.sezzle.com/llms.txt

Use this file to discover all available pages before exploring further.

Ce guide vous explique comment intégrer le SDK Sezzle iOS dans votre application. À la fin, votre application affichera les messages promotionnels Sezzle sur les pages produits et lancera le paiement Sezzle.

Prérequis

  • Cible de déploiement iOS 15.0+
  • Swift 5.9+
  • Un compte marchand Sezzle avec votre Clé API publique
  • Un serveur backend pour capturer les paiements après le paiement
Un exemple d’application fonctionnel est inclus dans le dépôt du SDK à Example/SezzleCheckoutExample. Il illustre toutes les variantes de widget et les deux modes de paiement.

1. Installation

  1. Dans Xcode, allez à File > Add Package Dependencies
  2. Entrez l’URL du dépôt :
https://github.com/sezzle/sezzle-merchant-sdk-ios.git
  1. Sélectionnez Up to Next Major Version à partir de la dernière version
  2. Ajoutez SezzleMerchantSDK à votre cible
Requirements: iOS 15.0+, Swift 5.9+

2. Configuration

Initialisez le SDK une fois au démarrage de l’application dans votre AppDelegate :
import SezzleMerchantSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        SezzleSDK.shared.configure(
            publicKey: "sz_pub_your_key_here",
            environment: .production  // use .sandbox for testing
        )
        return true
    }
}
ParamètreTypeDéfautDescription
publicKeyStringRequisVotre clé API publique Sezzle
environmentSezzleEnvironment.production.sandbox pour les tests, .production pour la production
N’incluez jamais votre clé API privée dans l’application. Le SDK utilise uniquement la clé publique. Utilisez votre clé privée côté serveur pour capturer les paiements.

3. Messages promotionnels

Ajoutez un SezzlePromotionalView à votre page produit pour afficher le prix des versements :
import SezzleMerchantSDK

let promoView = SezzlePromotionalView(
    amountInCents: 9999,  // $99.99
    presentingFrom: self   // UIViewController for modal presentation
)
view.addSubview(promoView)
Le widget affiche automatiquement le message correct en fonction du prix et se met à jour lorsque vous appelez :
promoView.update(amountInCents: 14999)  // price changed to $149.99
iOS Widgets

Tous les paramètres

SezzlePromotionalView(
    amountInCents: Int,
    currency: String = "USD",
    style: SezzlePromotionalStyle = .light,
    widgetConfig: SezzleWidgetConfig = .default,
    presentingFrom viewController: UIViewController
)
ParamètreTypeDéfautDescription
amountInCentsIntRequisPrix du produit en centimes (ex. : 4999 = 49,99 $)
currencyString"USD"Code de devise ISO 4217 (ex. : "USD", "CAD")
styleSezzlePromotionalStyle.light.light pour les fonds clairs, .dark pour les fonds sombres
widgetConfigSezzleWidgetConfig.defaultContrôle les seuils de prix et le paiement en 5 fois
presentingFromUIViewControllerRequisContrôleur de vue pour présenter la fenêtre d’information
Le widget détecte automatiquement le mode sombre et change de style via traitCollectionDidChange. Si vous souhaitez forcer un style spécifique, passez .light ou .dark explicitement.

Configuration du widget

Tous les paramètres de configuration sont optionnels — le widget fonctionne immédiatement avec des valeurs par défaut sensées :
ParamètreDéfautDescription
minPriceInCents3500 (35 $)Prix minimum pour afficher le widget
maxPriceInCents250000 (2 500 $)Prix maximum pour le court terme (PI4/PI5)
enablePayIn5trueAfficher “5 paiements” pour les prix égaux ou supérieurs au seuil PI5
pi5MinPriceInCents5000 (50 $)Seuil de prix pour le paiement en 5 fois
longTermConfignil (désactivé)Activer les paiements mensuels à long terme — définissez sur un SezzleLongTermConfig pour activer
Pour personnaliser, ne passez que les valeurs que vous souhaitez remplacer :
let config = SezzleWidgetConfig(
    longTermConfig: SezzleLongTermConfig(
        minPriceInCents: 25_000  // $250+ shows monthly payments
    )
)

let promoView = SezzlePromotionalView(
    amountInCents: 79900,
    widgetConfig: config,
    presentingFrom: self
)

Texte promotionnel personnalisé

Si vous avez besoin d’un contrôle total sur l’interface utilisateur, utilisez SezzlePromoDataHandler pour obtenir un NSAttributedString stylisé avec le logo Sezzle intégré :
SezzlePromoDataHandler.getMessage(amountInCents: 9999) { attributedString in
    myLabel.attributedText = attributedString
}

4. Paiement

Construire l’objet de paiement

let checkout = SezzleCheckout(
    customer: SezzleCustomer(
        email: "customer@example.com",
        firstName: "Jane",
        lastName: "Doe",
        phone: "+15551234567",
        billingAddress: SezzleAddress(
            street: "123 Main St",
            city: "Minneapolis",
            state: "MN",
            postalCode: "55401",
            countryCode: "US"
        )
    ),
    order: SezzleOrder(
        referenceId: "order-12345",
        description: "Wireless Earbuds",
        amount: SezzleAmount(amountInCents: 4599, currency: "USD"),
        items: [
            SezzleItem(
                name: "Wireless Earbuds",
                sku: "WE-001",
                quantity: 1,
                price: SezzleAmount(amountInCents: 3999, currency: "USD")
            )
        ],
        taxAmount: SezzleAmount(amountInCents: 350, currency: "USD"),
        shippingAmount: SezzleAmount(amountInCents: 250, currency: "USD")
    )
)

Champs client

ChampRequisDescription
emailOuiAdresse e-mail du client
firstNameNonPrénom du client
lastNameNonNom de famille du client
phoneNonNuméro de téléphone du client
dobNonDate de naissance ("YYYY-MM-DD")
billingAddressNonAdresse de facturation (SezzleAddress)
shippingAddressNonAdresse de livraison (SezzleAddress)
tokenizeNonTokeniser le client pour les commandes futures

Champs de commande

ChampRequisDescription
referenceIdOuiVotre identifiant de commande/référence interne
descriptionNonDescription de la commande
amountOuiMontant total de la commande en centimes + devise
intentNon.auth (par défaut, capture ultérieure depuis votre backend) ou .capture (capture automatique à la fin du paiement)
itemsNonDétails des articles
discountsNonArticles de remise ([SezzleDiscount])
taxAmountNonDétail du montant des taxes
shippingAmountNonDétail du montant de la livraison
metadataNonPaires clé-valeur personnalisées. Le SDK inclut automatiquement _sdk_platform, _sdk_version, _device_model, et _os_version — évitez d’utiliser des clés préfixées par _.
localeNonLangue du paiement (.enUS, .enCA, .frCA)
checkoutFinancingOptionsNonRestreindre à des plans spécifiques : .fourPayBiweekly, .fourPayMonthly, .sixPayMonthly. Optionnel — omettez pour laisser Sezzle afficher tous les plans éligibles.

Champs d’adresse (SezzleAddress)

ChampDescription
nameNom complet
streetAdresse postale ligne 1
street2Adresse postale ligne 2
cityVille
stateÉtat ou province
postalCodeCode postal
countryCodeCode pays ISO (ex. : "US")
phoneNuméro de téléphone

Démarrer le paiement

SezzleSDK.shared.startCheckout(
    checkout,
    from: self,            // presenting UIViewController
    delegate: self,        // SezzleCheckoutDelegate
    mode: .systemBrowser   // or .webView
)

Gérer le résultat

Conformez-vous à SezzleCheckoutDelegate :
extension ProductViewController: SezzleCheckoutDelegate {

    func checkoutDidComplete(result: SezzleCheckoutResult) {
        // For this flow, `result.orderUUID` is populated.
        // (For the server-driven flow, see Section 8.)
        if let orderUUID = result.orderUUID {
            // Send orderUUID to your backend to capture payment
            // POST /v2/order/{orderUUID}/capture
            print("Order completed: \(orderUUID)")
        }
    }

    func checkoutDidCancel() {
        // Customer closed checkout without completing
        print("Checkout cancelled")
    }

    func checkoutDidFail(error: SezzleError) {
        // Handle the error
        switch error {
        case .networkError(let underlying):
            print("Network error: \(underlying)")
        case .apiError(let statusCode, let message):
            print("API error \(statusCode): \(message)")
        case .browserDismissed:
            print("Browser dismissed")
        case .notConfigured:
            print("SDK not configured")
        case .invalidResponse:
            print("Invalid response")
        }
    }
}
Après checkoutDidComplete, envoyez result.orderUUID à votre serveur backend. Votre serveur doit appeler POST /v2/order/{orderUUID}/capture en utilisant votre privée clé API pour capturer le paiement. Consultez le Orders API pour plus de détails.

5. Mode WebView

Par défaut, le paiement s’ouvre dans ASWebAuthenticationSession (navigateur système). Pour garder l’utilisateur dans votre application, utilisez le mode WebView :
SezzleSDK.shared.startCheckout(
    checkout,
    from: self,
    delegate: self,
    mode: .webView
)
ModeAvantagesInconvénients
.systemBrowserSécurisé, partage les cookies Safari, recommandéBref changement de contexte
.webViewReste dans l’applicationPas de partage de cookies, l’utilisateur se connecte à chaque fois

6. Mode sombre

Le SDK s’adapte automatiquement au paramètre d’apparence de l’appareil. Le widget promotionnel, la fenêtre modale des versements et la fenêtre modale de paiement prennent tous en charge le mode sombre.
Light Mode
Si vous devez forcer un style spécifique (par exemple, votre application ne suit pas le paramètre système) :
let promoView = SezzlePromotionalView(
    amountInCents: 9999,
    style: .dark,  // force dark style
    presentingFrom: self
)

7. Gestion des erreurs

Toutes les erreurs sont transmises via SezzleCheckoutDelegate.checkoutDidFail(error:) :
ErreurQuandAction suggérée
.notConfiguredSezzleSDK.shared.configure() n’a pas été appeléAppeler configure() dans AppDelegate
.networkErrorPas d’internet, délai d’attente dépassé, échec DNSAfficher une option de réessai
.apiError(statusCode, message)L’API Sezzle a retourné une erreurVérifier le code de statut et le message
.browserDismissedL’utilisateur a fermé le navigateur/WebViewRetourner à la page produit
.invalidResponseFormat de réponse inattenduContacter le support Sezzle

8. Intégration pilotée par le serveur

Pour les marchands plus importants qui préfèrent une intégration entièrement pilotée par le serveur — sans clé publique sur l’appareil, avec le backend gérant la création de session, la capture et les remboursements — utilisez la surcharge alternative startCheckout introduite dans 1.2.0.

Fonctionnement

Votre backend crée la session de paiement via POST /v2/session avec des URL de rappel choisies par le marchand, puis transmet order.checkout_url ainsi que ces URL à l’application. Le SDK ouvre l’URL, intercepte la navigation vers vos URL de rappel et rend compte via SezzleCheckoutDelegate.checkoutDidComplete(result:) avec l’URL de rappel complète — vous pouvez ainsi encoder votre propre état dans la chaîne de requête et le récupérer à la fin.

Étape 1 — Le backend crée la session

Choisissez les URL de rappel que vous souhaitez — un schéma personnalisé comme yourapp-sezzle://... ou des liens profonds HTTPS. Vous pouvez encoder l’état dans la chaîne de requête (par ex. yourapp-sezzle://done?orderRef=12345) et le récupérer depuis le rappel du SDK. Conserver order.uuid côté serveur ; l’application n’a besoin que de order.checkout_url ainsi que des deux URL de rappel.
Ne mettez pas de PII, de jetons d’authentification ou quoi que ce soit de sensible dans la chaîne de requête de l’URL de rappel. L’URL de rappel est rendue dans le navigateur et peut être journalisée. Utilisez des références opaques (un orderRef aléatoire mappé côté serveur) — jamais l’e-mail, le téléphone, les données de paiement ou les jetons de session du client.Les schémas d’URL personnalisés ne sont pas non plus exclusifs — une autre application installée sur l’appareil peut enregistrer le même schéma et intercepter le rappel. Pour une sécurité maximale en production, utilisez les Universal Links (liens profonds HTTPS vérifiés) avec le mode .webView — ils sont liés à un domaine que vous contrôlez, de sorte que d’autres applications ne peuvent pas les revendiquer.

Étape 2 — L’application présente le paiement

SezzleSDK.shared.startCheckout(
    checkoutURL: URL(string: checkoutURL)!,                              // from order.checkout_url (String → URL)
    completeURL: URL(string: "yourapp-sezzle://checkout/done")!,         // matches your server's complete_url.href
    cancelURL:   URL(string: "yourapp-sezzle://checkout/cancelled")!,    // matches your server's cancel_url.href
    from: self,
    delegate: self,
    mode: .webView   // or .systemBrowser
)
SezzleSDK.shared.configure(publicKey:) est non requis pour ce flux — il n’y a rien à authentifier pour le SDK.

Étape 3 — Lire le résultat

func checkoutDidComplete(result: SezzleCheckoutResult) {
    guard let callbackURL = result.callbackURL else { return }
    let orderRef = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?
        .queryItems?
        .first(where: { $0.name == "orderRef" })?
        .value
    // Look up orderRef in your backend, then call /v2/order/{order.uuid}/capture
}

Notes

  • ASWebAuthenticationSession nécessite un schéma d’URL personnalisé pour le rappel (paramètre callbackURLScheme:). Les rappels HTTPS ne sont pas acceptés par l’API de session d’authentification. Pour les liens profonds basés sur HTTPS (par ex. pris en charge par Universal Links), utilisez le mode .webView — il intercepte la navigation directement via WKNavigationDelegate et fonctionne avec n’importe quel schéma.
  • Faites correspondre vos URL. Quel que soit ce que votre backend a transmis comme complete_url.href / cancel_url.href, transmettez les mêmes URL à startCheckout. Le SDK effectue la correspondance sur le schéma + l’hôte + le chemin ; les paramètres de requête de l’URL entrante sont lus par vous.
  • order.uuid réside sur votre serveur. Il n’est pas dans le checkout_url et n’est pas renvoyé — votre backend l’a déjà depuis la réponse de création de session.

9. Tests

Utilisez l’environnement sandbox pour les tests :
SezzleSDK.shared.configure(
    publicKey: "sz_pub_your_sandbox_key",
    environment: .sandbox
)
Utilisez les données de test pour effectuer des paiements de test en sandbox.
Passez à .production et à votre clé publique de production avant de publier sur l’App Store.