Android (Kotlin)

Le SDK Android vous permet d'encaisser des paiements Mobile Money, par carte et par portefeuille dans votre application, avec une interface de paiement prête à l'emploi construite avec Jetpack Compose.

Installer

dependencies {
    implementation("com.wajub:wajub-mobile-compose:1.3.0")
}

Rien à ajouter à votre manifeste ni à vos règles R8 : les artefacts apportent les leurs.

Démarrage rapide

Trois étapes, dont seule la deuxième s'exécute dans l'application.

1. Votre serveur crée le paiement avec POST /payments et sa clé secrète, puis transmet authorization_token à l'application. La clé secrète n'entre jamais dans l'application.
2. L'application affiche PaymentSheet avec ce jeton. onComplete reçoit le résultat une seule fois, à la fermeture de l'interface.
3. Votre serveur confirme le paiement, avec le webhook payment.succeeded ou GET /payments/{id}, avant de livrer. Le résultat dans l'application est ce que le payeur a vu, pas une preuve de paiement.

import androidx.compose.runtime.*
import androidx.compose.runtime.saveable.rememberSaveable
import com.wajub.mobile.checkout.CheckoutResult
import com.wajub.mobile.checkout.PresentOptions
import com.wajub.mobile.ui.PaymentSheet

@Composable
fun Checkout(authorizationToken: String) {
    var paying by rememberSaveable { mutableStateOf(true) }

    if (paying) {
        PaymentSheet(PresentOptions(sessionToken = authorizationToken)) { result ->
            paying = false
            when (result) {
                is CheckoutResult.Complete -> showReceipt(result.payment) // confirm on your server first
                is CheckoutResult.Processing -> showPending()              // money may still move
                is CheckoutResult.Failed -> showError(result.error.message)
                is CheckoutResult.Cancelled -> Unit                        // result.reason, result.redirectUrl
            }
        }
    }
}

CheckoutResult est une classe scellée : le when est exhaustif sans else. L'interface résiste aux changements de configuration, comme une rotation ou un changement de langue. Afficher une deuxième PaymentSheet pendant qu'une autre est ouverte règle la deuxième aussitôt avec Failed et le code sheet_already_presented, sans toucher à la première.

Options

PresentOptions est une data class de com.wajub.mobile.checkout. Seul sessionToken doit être fourni.

Callbacks et états

CheckoutCallbacks prend neuf lambdas facultatives. Elles s'exécutent sur le thread principal, et un callback qui lève une exception est journalisé sans casser l'interface.

PresentOptions(
    sessionToken = token,
    callbacks = CheckoutCallbacks(
        onReady = { event -> },          // ReadyEvent: sessionId, environment, amount, currency, methods
        onStateChange = { event -> },    // StateChangeEvent: state, method
        onLoadError = { error -> },      // WajubError: the sheet cannot offer a payment
        onPaymentStarted = { event -> }, // PaymentStartedEvent: method, channel
        onRedirect = { event -> },       // RedirectEvent: url, right before Custom Tabs opens
        onSuccess = { payment -> },      // PaymentSuccess
        onError = { error -> },          // WajubError: every failure the payer sees
        onCancel = { event -> },         // CancelEvent: reason, redirectUrl
        onComplete = { result -> },      // the CheckoutResult PaymentSheet's onComplete receives
    ),
)

StateChangeEvent.state est un CheckoutState. Sa propriété value donne le nom de l'état en chaîne, ce qui compte pour l'un d'eux : la constante est THREE_DS_REQUIRED et sa valeur 3DS_REQUIRED.

Ce que voit le payeur dans chaque état est sur SDKs mobiles.

Résultats

Chaque résultat porte aussi status, son nom en chaîne : complete, processing, failed, cancelled. CancelReason vaut PayerCancelled, Dismissed ou HostGone, avec sa chaîne dans value.

PaymentSuccess porte id (l'identifiant Wajub du paiement, celui que prend GET /payments/{id}), reference (la vôtre), amount (ce que le payeur a payé, frais compris, en unité principale), currency, method, status (toujours success), timestamp (ISO 8601) et receiptUrl.

L'interface n'affiche jamais d'échec tant que l'issue n'est pas connue : elle affiche « Paiement en cours » et continue d'attendre, et la fermer à ce moment donne Processing. Si le processus de votre application meurt, aucun résultat n'arrive : au lancement suivant, interrogez votre serveur.

Annuler et fermer

Le payeur ferme l'interface avec son bouton de fermeture, en la faisant glisser vers le bas, avec le bouton Retour, ou en touchant à l'extérieur.

Annuler le paiement, proposé sur la liste des moyens et sur un formulaire, annule le paiement pour de bon et donne Cancelled avec PayerCancelled et le redirectUrl du marchand.

Votre application qui retire le composable, ou termine son activité, n'est pas le payeur qui ferme l'interface : elle se règle sur Cancelled avec HostGone avant toute tentative de paiement, sur Processing une fois une tentative lancée, sur Complete après un succès, et n'annule jamais le paiement. Voir SDKs mobiles.

Apparence

L'option appearance règle l'apparence de l'interface. Ses clés, ses presets et ses variables sont sur Apparence.

import androidx.compose.ui.text.font.Font
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
import com.wajub.mobile.checkout.Appearance
import com.wajub.mobile.checkout.AppearanceVariables
import com.wajub.mobile.ui.WajubFonts

// Once, before showing the sheet (in Application.onCreate, say): a font your app ships.
WajubFonts.register(
    "Poppins",
    FontFamily(Font(R.font.poppins_regular), Font(R.font.poppins_semibold, FontWeight.SemiBold)),
)

PresentOptions(
    sessionToken = token,
    appearance = Appearance(
        theme = "stripe",                 // a preset: stripe, night, flat, none, or a scheme: light, dark, auto
        colorScheme = "auto",             // follows the phone
        variables = AppearanceVariables(
            colorPrimary = "#0F766E",
            borderRadius = "12px",
            fontFamily = "Poppins",          // the name registered above
        ),
        buttonTextColor = "#FFFFFF",      // top-level keys work too
        inherit = true,                   // your MaterialTheme fills what you leave unset
    ),
)

• Chaque valeur est une String. Les couleurs s'écrivent #rgb, #rrggbb, #rrggbbaa, rgb() ou rgba() ; les longueurs "8px", "8" ou "0.5rem". Une valeur illisible est ignorée.
• inherit = true prend dans le MaterialTheme de votre application ce que vous laissez vide.
• Une fontFamily n'atteint l'interface qu'une fois enregistrée par votre application avec WajubFonts.register(name, family) ; unregister(name) la retire.
• Le logo, le nom commercial et les couleurs du marchand dans le Dashboard complètent ce que vous laissez vide, et un marchand en marque blanche masque « Sécurisé par Wajub ».
• disableAnimations = true coupe les animations de l'interface.

Mobile Money

Le payeur choisit le pays et l'opérateur, et saisit le numéro avec l'indicatif du pays. Après Payer, l'interface affiche « Validez le paiement sur votre téléphone » avec l'instruction de l'opérateur jusqu'à l'issue du paiement.

PresentOptions(
    sessionToken = token,
    mobileMoney = MobileMoneyOptions(country = "CI", countryLocked = true, operatorMode = OperatorMode.Detect),
)

Pour votre propre formulaire, MobileMoney vérifie, met en forme et lit un numéro : isValid, formatAsYouType, detectOperator, et data() pour les pays et leurs indicatifs.

Cartes

Les cartes ne demandent aucune configuration dans votre application. Selon le paiement, le payeur saisit sa carte dans l'interface ou sur une page sécurisée du prestataire de paiement, ouverte dans Custom Tabs ; Continuer le paiement rouvre cette page si le payeur revient avant de payer. En sandbox, l'interface affiche un formulaire de carte de test.

Étapes de confirmation

Certains paiements demandent une information de plus au payeur après Payer. Chaque étape a son écran et affiche les essais restants après une réponse erronée.

Une réponse erronée avec des essais restants reste sur l'étape. Trop d'essais, ou une étape expirée, met fin à la tentative, et le payeur peut recommencer. Voir SDKs mobiles.

Erreurs

WajubError étend Exception. L'interface la transmet à onLoadError, à onError et à CheckoutResult.Failed.

Codes que vous rencontrerez : insufficient_funds, payment_declined, payment_attempt_ended (refusé, rien n'a été débité), payment_failed, payment_cancelled, session_expired, shield_blocked, merchant_restricted, rate_limited, session_terminal_expired, unsupported_action, redirect_unavailable, sheet_already_presented. ErrorCatalog.message(code, WajubLanguage.Fr, null) donne le message d'un code en anglais ou en français. Tous les codes sont sur SDKs mobiles.

Votre propre interface

CheckoutController, dans wajub-mobile-core, est toute l'interface de paiement sans son UI : il mène le paiement, appelle les mêmes callbacks et se termine par le même CheckoutResult, pendant que vous dessinez les écrans.

import com.wajub.mobile.WajubMobile
import com.wajub.mobile.checkout.CheckoutController
import com.wajub.mobile.checkout.PresentOptions
import com.wajub.mobile.checkout.SheetScreen
import com.wajub.mobile.ui.HostedRedirectLauncher

// In your ViewModel. token comes from your server, appContext is your Application.
val controller = CheckoutController(
    WajubMobile.createSession(token),
    PresentOptions(sessionToken = token),
    viewModelScope,
).apply {
    urlOpener = { url -> HostedRedirectLauncher.open(appContext, url) } // opens Custom Tabs
    onFinished = { result -> /* hide your screens, then handle the result */ }
    start()
}

// In your composable:
val screen by controller.screen.collectAsState()
when (val s = screen) {
    SheetScreen.Loading -> MyLoader()
    is SheetScreen.Methods -> MyMethodList(s.methods, onPick = controller::selectMethod)
    is SheetScreen.Form -> MyForm(s, onPhone = controller::setPhone, onPay = controller::payMobileMoney)
    is SheetScreen.Success -> MyReceipt(s.payment)
    else -> MyStatus(s) // approval, steps, "Payment in progress", failures…
}

• Transmettez les actions du payeur : selectMethod, setCountry, setPhone, pickOperator, payMobileMoney, payWallet, setCardField, payCard, payStripe, setStepField, submitStep, resendStep, continuePayment, tryAgain, cancelPayment, close et dismiss.
• Appelez onReturn() quand votre application reprend la main, et hostGone() quand votre écran disparaît pour de bon. Chaque appel se fait sur le thread principal, où s'exécutent les callbacks.
• Quand le card?.flavor d'un formulaire est un CardFlavor.Stripe, affichez le CardInputWidget de Stripe et payez avec controller.payStripe { StripeTokenizer.createPaymentMethod(context, stripe.publishableKey, card) }, où stripe est ce CardFlavor.Stripe et card le paymentMethodCard du widget. Ajoutez implementation("com.stripe:stripe-android:21.2.0") à votre propre fichier de build : le module Compose n'expose pas Stripe à votre code.

WajubSession, le client de plus bas niveau d'un paiement, est documenté dans le README du paquet.

Confidentialité

Pour effectuer le paiement, le SDK envoie à Wajub ce que saisit le payeur. Pour la prévention de la fraude, il envoie aussi des informations de base sur l'appareil et un identifiant d'installation aléatoire, qui n'est pas l'identifiant publicitaire. Ce qu'il faut déclarer dans le formulaire de sécurité des données de Google Play, catégorie par catégorie, est sur SDKs mobiles.

Tests

Créez le paiement avec une clé sandbox, et tout le parcours se déroule en sandbox, interface comprise, qui affiche un badge « MODE TEST ». Rien à changer dans l'application. Les numéros et les cartes de test sont sur Scénarios de test.

wajub-mobile-core ne dépend pas d'Android : il tourne dans un simple test unitaire JVM, sans émulateur.