Passer au contenu principal
Ce guide vous explique comment intégrer le SDK iOS Sezzle 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. Saisissez l’URL du dépôt :
  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 :
N’incluez jamais votre clé privée API 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 la tarification en versements :
Le widget affiche automatiquement le message correct en fonction du prix et se met à jour lorsque vous appelez :
iOS Widgets

Widgets promotionnels à différents niveaux de prix

Tous les paramètres

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 : Pour personnaliser, ne passez que les valeurs que vous souhaitez remplacer :

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é :

4. Paiement

Construire l’objet de paiement

Champs client

Champs de commande

Champs d’adresse (SezzleAddress)

Démarrer le paiement

Gérer le résultat

Conformez-vous à SezzleCheckoutDelegate :
Après checkoutDidComplete, envoyez result.orderUUID vers votre serveur backend. Votre serveur doit appeler POST /v2/order/{orderUUID}/capture en utilisant votre privée clé API pour capturer le paiement. Consultez l’ 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 :

Appareils multi-utilisateurs — effacement de la session Sezzle à la déconnexion

Le WKWebsiteDataStore.default() est un store persistant unique à l’échelle de l’application, hérité par chaque WebView avec la configuration par défaut. Les cookies définis lors du paiement .webView d’un utilisateur (jetons d’authentification, identifiants de session) persistent entre les utilisateurs sur le même appareil — ainsi, si votre application prend en charge plusieurs utilisateurs (par exemple, un flux de déconnexion/connexion sur un appareil partagé), la première tentative BNPL de l’utilisateur suivant peut reprendre la session Sezzle de l’utilisateur précédent et exposer son état (refus de limite de crédit, etc.) au mauvais client. À partir de 1.2.2, appelez SezzleSDK.shared.clearWebViewData() depuis votre flux de déconnexion pour effacer les cookies et le stockage Web de Sezzle avant que l’utilisateur suivant ne se connecte :
L’effacement est limité aux domaines propres à Sezzle — vos autres cookies et stockage Web ne sont pas affectés. Peut être appelé de manière répétée en toute sécurité ; peut être appelé en toute sécurité même si aucun paiement Sezzle n’a jamais été effectué. L’opération est asynchrone ; le gestionnaire de complétion optionnel se déclenche sur l’acteur principal. .systemBrowser le mode partage les cookies avec Safari via ASWebAuthenticationSession et n’est pas affecté — si vos utilisateurs ont besoin de les effacer, ils doivent le faire directement dans Safari.

6. Mode sombre

Le SDK s’adapte automatiquement au paramètre d’apparence de l’appareil. Le widget promotionnel, la modale d’acomptes et la modale de paiement prennent tous en charge le mode sombre.
Light Mode
Si vous avez besoin de forcer un style spécifique (par exemple, votre application ne suit pas le paramètre système) :

7. Gestion des erreurs

Toutes les erreurs sont transmises via SezzleCheckoutDelegate.checkoutDidFail(error:) :

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, 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 URLs de rappel choisies par le marchand, puis transmet order.checkout_url ainsi que ces URLs à l’application. Le SDK ouvre l’URL, intercepte la navigation vers vos URLs de rappel, et rapporte le résultat 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 complétion.

Étape 1 — Le backend crée la session

Choisissez les URLs 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 exemple yourapp-sezzle://done?orderRef=12345) et le récupérer depuis le rappel du SDK. Persister order.uuid côté serveur ; l’application n’a besoin que de order.checkout_url ainsi que des deux URLs de rappel.
Ne pas mettre de PII, de jetons d’authentification, ni 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.configure(publicKey:) est non requis pour ce flux — il n’y a rien à authentifier pour le SDK.

Étape 3 — Lire le résultat

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 exemple, 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 URLs. Quelles que soient les URLs que votre backend a transmises en tant que complete_url.href / cancel_url.href, transmettez les mêmes URLs à 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 le possède déjà depuis la réponse de création de session.

9. Tests

Utilisez l’environnement sandbox pour les tests :
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.