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 Android 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
Gradle (Kotlin DSL)
Gradle (Groovy)
Ajoutez à votre module d’application build.gradle.kts :dependencies {
implementation("com.sezzle:sezzle-merchant-sdk:1.2.1")
}
Ajoutez à votre module d’application build.gradle :dependencies {
implementation 'com.sezzle:sezzle-merchant-sdk:1.2.1'
}
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 seule fois au démarrage de l’application dans votre Application class:
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.
Ajoutez un SezzlePromotionalView à votre écran produit pour afficher la tarification en versements :
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 :
promoView.update(amountInCents = 14999) // price changed to $149.99
Tous les paramètres
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.
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 les paiements à 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 :
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é :
SezzlePromoDataHandler.getMessage(
context = this,
amountInCents = 9999
) { spannableString ->
myTextView.text = spannableString
}
4. Paiement
Construire l’objet de paiement
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 identifiant 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 (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<SezzleDiscount>) |
taxAmount | Non | Détail du montant des taxes |
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
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 :
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 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 :
SezzleSDK.startCheckout(
checkout = checkout,
activity = this,
listener = checkoutListener,
mode = SezzleCheckoutMode.WEB_VIEW
)
| 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 |
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.
Si vous devez forcer un style spécifique :
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é | Appeler 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 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.
É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 pas mettre 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
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 pas requis pour ce flux — il n’y a rien à authentifier pour le SDK.
Étape 3 — Lire le résultat
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 mode
SYSTEM_BROWSER 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 :
<activity
android:name="com.sezzle.sdk.checkout.SezzleRedirectActivity"
android:exported="true"
android:launchMode="singleTask"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
tools:replace="android:exported">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="yourapp-sezzle" android:host="checkout" />
</intent-filter>
</activity>
WEB_VIEW mode ne nécessite aucune modification du manifeste — tout schéma est intercepté directement par le client WebView.
Remarques
- Faites correspondre vos URL. Quelle que soit l’URL que votre backend a transmise en tant que
complete_url.href / cancel_url.href, transmettez la même Uri à 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.configure(
publicKey = "sz_pub_your_sandbox_key",
environment = SezzleEnvironment.SANDBOX
)
Utilisez les données de test pour effectuer des paiements de test en sandbox.
Passez à SezzleEnvironment.PRODUCTION et votre clé publique de production avant de publier sur le Play Store.