> ## 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. # Android Ce guide vous explique comment intégrer le SDK Android Sezzle dans votre application. À la fin, votre application affichera les messages promotionnels Sezzle sur les pages produits et lancera le paiement Sezzle. ### Prérequis * Android 6.0+ (API 23), compileSdk 35+ * Kotlin ou Java * 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/. Il illustre toutes les variantes de widget et les deux modes de paiement. ## 1. Installation Ajoutez à votre module d'application `build.gradle.kts` : ```kotlin theme={"system"} dependencies { implementation("com.sezzle:sezzle-merchant-sdk:1.2.7") } ``` Ajoutez à votre module d'application `build.gradle` : ```groovy theme={"system"} dependencies { implementation 'com.sezzle:sezzle-merchant-sdk:1.2.7' } ``` Le SDK est publié sur Maven Central. Aucune configuration de dépôt supplémentaire n'est nécessaire. **Requirements:** Android 6.0+ (API 23), compileSdk 35+ ## 2. Configuration Initialisez le SDK une fois au démarrage de l'application dans votre `Application` class: ```kotlin theme={"system"} import com.sezzle.sdk.SezzleSDK import com.sezzle.sdk.SezzleEnvironment class MyApplication : Application() { override fun onCreate() { super.onCreate() SezzleSDK.configure( publicKey = "sz_pub_your_key_here", environment = SezzleEnvironment.PRODUCTION // use SANDBOX for testing ) } } ``` | Paramètre | Type | Défaut | Description | | ------------- | ------------------- | ------------ | --------------------------------------------------------- | | `publicKey` | `String` | Requis | Votre clé API publique Sezzle | | `environment` | `SezzleEnvironment` | `PRODUCTION` | `SANDBOX` pour les tests, `PRODUCTION` pour la production | N'incluez jamais votre **privée** clé 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 écran produit pour afficher la tarification en versements : ```kotlin theme={"system"} import com.sezzle.sdk.SezzlePromotionalView val promoView = SezzlePromotionalView( context = this, amountInCents = 9999 // $99.99 ) promoView.setPresenter(this) // Activity for modal presentation container.addView(promoView) ``` Le widget affiche automatiquement le message correct en fonction du prix et se met à jour lorsque vous appelez : ```kotlin theme={"system"} promoView.update(amountInCents = 14999) // price changed to $149.99 ``` Android Widgets ### Tous les paramètres ```kotlin theme={"system"} SezzlePromotionalView( context: Context, amountInCents: Int, currency: String = "USD", style: SezzlePromotionalStyle = SezzlePromotionalStyle.LIGHT, widgetConfig: SezzleWidgetConfig = SezzleWidgetConfig.DEFAULT ) ``` | Paramètre | Type | Défaut | Description | | --------------- | ------------------------ | --------- | ------------------------------------------------------------ | | `amountInCents` | `Int` | Requis | Prix du produit en centimes (ex. : 4999 = 49,99 \$) | | `currency` | `String` | `"USD"` | Code de devise ISO 4217 (ex. : `"USD"`, `"CAD"`) | | `style` | `SezzlePromotionalStyle` | `LIGHT` | `LIGHT` pour les fonds clairs, `DARK` pour les fonds sombres | | `widgetConfig` | `SezzleWidgetConfig` | `DEFAULT` | Contrôle les seuils de tarification et le paiement en 5 fois | Le widget détecte automatiquement le mode sombre et change de style automatiquement. Si vous souhaitez forcer un style spécifique, passez `SezzlePromotionalStyle.LIGHT` ou `SezzlePromotionalStyle.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ètre | Défaut | Description | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------ | | `minPriceInCents` | `3500` (35 \$) | Prix minimum pour afficher le widget | | `maxPriceInCents` | `250000` (2 500 \$) | Prix maximum pour le court terme (PI4/PI5) | | `enablePayIn5` | `true` | Afficher "5 paiements" pour les prix égaux ou supérieurs au seuil PI5 | | `pi5MinPriceInCents` | `5000` (50 \$) | Seuil de prix pour le paiement en 5 fois | | `longTermConfig` | `null` (désactivé) | Activer les paiements mensuels à long terme — définir sur un `SezzleLongTermConfig` pour activer | Pour personnaliser, ne passez que les valeurs que vous souhaitez remplacer : ```kotlin theme={"system"} val config = SezzleWidgetConfig( longTermConfig = SezzleLongTermConfig( minPriceInCents = 25_000 // $250+ shows monthly payments ) ) val promoView = SezzlePromotionalView( context = this, amountInCents = 79900, widgetConfig = config ) ``` ### Texte promotionnel personnalisé Si vous avez besoin d'un contrôle total sur l'interface utilisateur, utilisez `SezzlePromoDataHandler` pour obtenir un `SpannableString` stylisé avec le logo Sezzle intégré : ```kotlin theme={"system"} SezzlePromoDataHandler.getMessage( context = this, amountInCents = 9999 ) { spannableString -> myTextView.text = spannableString } ``` ## 4. Paiement ### Construire l'objet de paiement ```kotlin theme={"system"} val 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 = listOf( 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 | Champ | Requis | Description | | ----------------- | ------ | ---------------------------------------------- | | `email` | Oui | Adresse e-mail du client | | `firstName` | Non | Prénom du client | | `lastName` | Non | Nom de famille du client | | `phone` | Non | Numéro de téléphone du client | | `dob` | Non | Date de naissance (`"YYYY-MM-DD"`) | | `billingAddress` | Non | Adresse de facturation (`SezzleAddress`) | | `shippingAddress` | Non | Adresse de livraison (`SezzleAddress`) | | `tokenize` | Non | Tokeniser le client pour les commandes futures | #### Champs de commande | Champ | Requis | Description | | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `referenceId` | Oui | Votre ID de commande/référence interne | | `description` | Non | Description de la commande (par défaut : "Mobile SDK Order") | | `amount` | Oui | Montant total de la commande en centimes + devise | | `intent` | Non | [`AUTH`](/fr/docs/api/core/sessions/postv2session#body-order-intent) (par défaut, capture ultérieure depuis votre backend) ou `CAPTURE` (capture automatique à la fin du paiement) | | `items` | Non | Détails des articles de la commande | | `discounts` | Non | Articles de remise (`List`) | | `taxAmount` | Non | Détail du montant de la taxe | | `shippingAmount` | Non | Détail du montant de la livraison | | `metadata` | Non | Paires 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 `_`. | | `locale` | Non | Langue du paiement (`EN_US`, `EN_CA`, `FR_CA`) | | `checkoutFinancingOptions` | Non | Restreindre à des plans spécifiques : `FOUR_PAY_BIWEEKLY`, `FOUR_PAY_MONTHLY`, `SIX_PAY_MONTHLY`. Optionnel — omettez pour laisser Sezzle afficher tous les plans éligibles. | #### Champs d'adresse (`SezzleAddress`) | Champ | Description | | ------------- | ---------------------------- | | `name` | Nom complet | | `street` | Ligne 1 de l'adresse postale | | `street2` | Ligne 2 de l'adresse postale | | `city` | Ville | | `state` | État ou province | | `postalCode` | Code postal | | `countryCode` | Code pays ISO (ex. : `"US"`) | | `phone` | Numéro de téléphone | ### Démarrer le paiement ```kotlin theme={"system"} SezzleSDK.startCheckout( checkout = checkout, activity = this, // ComponentActivity listener = checkoutListener, // SezzleCheckoutListener mode = SezzleCheckoutMode.SYSTEM_BROWSER // or WEB_VIEW ) ``` Le `activity` paramètre doit être un `ComponentActivity` (ex. : `AppCompatActivity`). Le SDK utilise l'API Activity Result en interne. ### Gérer le résultat Implémentez `SezzleCheckoutListener` : ```kotlin theme={"system"} private val checkoutListener = object : SezzleCheckoutListener { override fun onCheckoutComplete(result: SezzleCheckoutResult) { // For this flow, `result.orderUUID` is populated. // (For the server-driven flow, see Section 8.) result.orderUUID?.let { orderUUID -> // Send orderUUID to your backend to capture payment // POST /v2/order/{orderUUID}/capture Log.d("Sezzle", "Order completed: $orderUUID") } } override fun onCheckoutCancel() { // Customer closed checkout without completing Log.d("Sezzle", "Checkout cancelled") } override fun onCheckoutError(error: SezzleError) { // Handle the error when (error) { is SezzleError.NetworkError -> Log.e("Sezzle", "Network error: ${error.underlying}") is SezzleError.ApiError -> Log.e("Sezzle", "API error ${error.statusCode}: ${error.apiMessage}") is SezzleError.BrowserDismissed -> Log.d("Sezzle", "Browser dismissed") is SezzleError.NotConfigured -> Log.e("Sezzle", "SDK not configured") is SezzleError.InvalidResponse -> Log.e("Sezzle", "Invalid response") } } } ``` Après `onCheckoutComplete`, 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. Voir le [Orders API](/fr/docs/api/core/orders/postv2capturebyorder) pour plus de détails. ## 5. Mode WebView Par défaut, le paiement s'ouvre dans Chrome Custom Tabs — un onglet de navigateur sécurisé qui s'exécute dans son propre processus et partage les cookies avec Chrome (connexion plus rapide pour les utilisateurs Sezzle récurrents). Pour garder l'utilisateur dans votre application, utilisez le mode WebView : ```kotlin theme={"system"} SezzleSDK.startCheckout( checkout = checkout, activity = this, listener = checkoutListener, mode = SezzleCheckoutMode.WEB_VIEW ) ``` ### Variante sécurisée pour le cycle de vie (recommandée pour WebView) Si votre activité hôte peut être détruite et recréée pendant que le paiement est à l'écran — par exemple sous l'option développeur Android « Ne pas conserver les activités », sous des limites agressives de processus en arrière-plan, ou sous une pression mémoire réelle sur les appareils à faible RAM — préférez la `startCheckoutForResult` surcharge introduite dans `1.2.4`. Elle transmet le résultat via l'[Activity Result API](https://developer.android.com/training/basics/intents/result) d'Android, qui se rattache lors de la recréation de l'activité, de sorte que le rappel atteint de manière fiable l'instance active lorsque le paiement se termine. Le chemin basé sur les listeners ci-dessus stocke votre rappel dans un champ statique ; si votre activité est recréée en cours de paiement, ce rappel peut cibler une instance détruite et le résultat peut être perdu. Enregistrez le launcher en tant que champ sur votre activité (Android exige que `registerForActivityResult` soit appelé avant que l'activité n'atteigne `STARTED`) : ```kotlin theme={"system"} class CheckoutActivity : ComponentActivity() { private val sezzleLauncher = registerForActivityResult(SezzleCheckoutContract()) { result -> when (result) { is SezzleCheckoutContract.Output.Complete -> { // result.orderUuid — SDK-creates-session flow // result.callbackUrl — server-driven flow } SezzleCheckoutContract.Output.Cancel -> { // User dismissed checkout (X close, back press, cancelUrl navigation) } is SezzleCheckoutContract.Output.Error -> { // result.code — one of SezzleCheckoutContract.ErrorCode constants // result.message — human-readable } } } private fun launchSezzle() { SezzleSDK.startCheckoutForResult( launcher = sezzleLauncher, checkout = checkout, onError = { error -> /* pre-launch failure: NotConfigured / NetworkError / ApiError */ }, ) } } ``` Pour le flux piloté par le serveur, utilisez la surcharge basée sur l'URL : ```kotlin theme={"system"} SezzleSDK.startCheckoutForResult( launcher = sezzleLauncher, checkoutUrl = checkoutUrl, completeUrl = completeUrl, cancelUrl = cancelUrl, onError = { error -> /* launcher.launch threw — host activity was gone */ }, ) ``` Ce point d'entrée utilise toujours le mode `WEB_VIEW`. Pour le paiement `SYSTEM_BROWSER` (Chrome Custom Tabs), continuez à utiliser le `startCheckout` basé sur les listeners — le flux Custom Tabs a un profil de recréation différent et ne présente pas le même risque de cycle de vie. System Browser WebView | Mode | Avantages | Inconvénients | | ---------------- | ------------------------------------------------ | ------------------------------------------------------------------ | | `SYSTEM_BROWSER` | Sécurisé, partage les cookies Chrome, recommandé | Bref changement de contexte | | `WEB_VIEW` | Reste dans l'application | Pas de partage de cookies, l'utilisateur se connecte à chaque fois | ### Appareils multi-utilisateurs — effacement de la session Sezzle lors de la déconnexion L'`CookieManager` d'Android est un singleton persistant à l'échelle de l'application. Les cookies définis lors du paiement `WEB_VIEW` 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.5`, appelez `SezzleSDK.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 : ```kotlin theme={"system"} fun onUserLogout() { // ...clear your own session state... SezzleSDK.clearWebViewData() } ``` L'effacement est limité aux domaines propres à Sezzle — vos autres cookies et stockage Web ne sont pas touchés. Peut être appelé de manière répétée ; peut être appelé même si aucun paiement Sezzle n'a jamais été effectué. Préserve votre paramètre `CookieManager.acceptCookie()` à l'échelle de l'application (les modes confidentialité/RGPD/DNT ne sont pas modifiés silencieusement). `SYSTEM_BROWSER` Le mode partage les cookies avec Chrome et n'est pas affecté — si vos utilisateurs ont besoin de les effacer, ils doivent le faire dans Chrome lui-même. ## 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 Dark Mode Si vous devez forcer un style spécifique : ```kotlin theme={"system"} val promoView = SezzlePromotionalView( context = this, amountInCents = 9999, style = SezzlePromotionalStyle.DARK // force dark style ) ``` ## 7. Gestion des erreurs Toutes les erreurs sont transmises via `SezzleCheckoutListener.onCheckoutError(error)` : | Erreur | Quand | Action suggérée | | ---------------------------------- | -------------------------------------------------- | ----------------------------------------------------- | | `NotConfigured` | `SezzleSDK.configure()` n'a pas été appelé | Appelez `configure()` dans votre `Application` classe | | `NetworkError` | Pas d'internet, délai d'attente dépassé, échec DNS | Afficher une option de réessai | | `ApiError(statusCode, apiMessage)` | L'API Sezzle a retourné une erreur | Vérifier le code de statut et le message | | `BrowserDismissed` | L'utilisateur a fermé le navigateur/WebView | Retourner à la page produit | | `InvalidResponse` | Format de réponse inattendu | Contacter 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`](/fr/docs/api/core/sessions/postv2session) 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 rapporte via `SezzleCheckoutListener.onCheckoutComplete(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. ```mermaid theme={"system"} sequenceDiagram participant App as Merchant App participant Backend as Merchant Backend participant SDK as Sezzle SDK participant API as Sezzle API App->>Backend: 1. Request checkout Backend->>API: 2. POST /v2/session (with merchant callback URLs) API-->>Backend: order.uuid + order.checkout_url Backend-->>App: 3. checkout_url + callback URLs App->>SDK: 4. startCheckout(checkoutUrl, completeUrl, cancelUrl, …) SDK-->>App: 5. onCheckoutComplete(result.callbackURL) App->>Backend: 6. Map callback URL state → orderUUID Backend->>API: 7. Capture payment ``` ### É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 exemple `yourapp-sezzle://done?orderRef=12345`) et le récupérer depuis le rappel du SDK. Persistez `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 également **pas 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 **App Links** (liens profonds HTTPS vérifiés) sur Android — 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 ```kotlin theme={"system"} SezzleSDK.startCheckout( checkoutUrl = checkoutUrl, // from order.checkout_url (String — pass through as-is) completeUrl = Uri.parse("yourapp-sezzle://checkout/done"), // matches your server's complete_url.href cancelUrl = Uri.parse("yourapp-sezzle://checkout/cancelled"), // matches your server's cancel_url.href activity = this, listener = checkoutListener, mode = SezzleCheckoutMode.WEB_VIEW // or SYSTEM_BROWSER ) ``` `SezzleSDK.configure(...)` est **non** requis pour ce flux — il n'y a rien à authentifier pour le SDK. ### Étape 3 — Lire le résultat ```kotlin theme={"system"} override fun onCheckoutComplete(result: SezzleCheckoutResult) { val callbackURL = result.callbackURL ?: return val orderRef = callbackURL.getQueryParameter("orderRef") // Look up orderRef in your backend, then call /v2/order/{order.uuid}/capture } ``` ### Note sur le manifeste pour le mode `SYSTEM_BROWSER` `SYSTEM_BROWSER` Le mode ouvre le paiement dans Chrome Custom Tabs et achemine la redirection via le système d'intent du système d'exploitation. Le SDK inclut un intent-filter pour `sezzle-sdk://checkout` uniquement — si vous utilisez un schéma de rappel personnalisé, enregistrez un intent-filter pour votre schéma dans votre propre `AndroidManifest.xml`, pointant vers `SezzleRedirectActivity` : ```xml theme={"system"} ``` `WEB_VIEW` Le mode n'a pas besoin de modification du manifeste — tout schéma est intercepté directement par le client WebView. ### Notes * **Faites correspondre vos URL.** Quelles que soient les valeurs que votre backend a transmises en tant que `complete_url.href` / `cancel_url.href`, transmettez les mêmes `Uri` à `startCheckout`. Le SDK effectue la correspondance sur le schéma + l'hôte + le chemin ; les paramètres de requête sur 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 : ```kotlin theme={"system"} SezzleSDK.configure( publicKey = "sz_pub_your_sandbox_key", environment = SezzleEnvironment.SANDBOX ) ``` Utilisez les [données de test](/fr/docs/api/test-cards) pour effectuer des paiements test en sandbox. Passez en `SezzleEnvironment.PRODUCTION` et votre clé publique live avant de publier sur le Play Store.