iOS (Swift)

Le SDK iOS encaisse les paiements dans votre application native. Il présente les paiements Mobile Money, par carte et par portefeuille dans une interface de paiement SwiftUI, sans WebView pour les écrans de Wajub, et ouvre dans Safari la page carte d'un prestataire ou une vérification 3-D Secure. Il implémente le contrat mobile commun, la spec v2 : les mêmes options, callbacks, états, résultats, erreurs et le même objet d'apparence que les SDKs Flutter, Android et React Native et que Wajub.js 1.8.

Installer

Le package s'ajoute avec Swift Package Manager. Dans Xcode, File › Add Package Dependencies… avec https://github.com/wajubhq/wajub-ios, ou dans votre propre Package.swift :

dependencies: [
    .package(url: "https://github.com/wajubhq/wajub-ios.git", from: "1.0.0"),
],
targets: [
    .target(name: "App", dependencies: [
        .product(name: "WajubMobileUI", package: "wajub-ios"),
    ]),
]

Le package propose deux produits, et WajubMobileUI installe WajubMobile avec lui.

Importez WajubMobile seul quand vous dessinez vos propres écrans de paiement.

Démarrage rapide

Votre serveur crée le paiement, l'application présente l'interface avec son jeton, et votre serveur confirme le résultat. Aucun élément du package n'appelle /payments ni ne détient de clé secrète.

1. Créez le paiement sur votre serveur avec POST /payments et votre clé secrète, puis transmettez son authorization_token à l'application par votre propre endpoint.

struct CheckoutResponse: Decodable {
    let authorizationToken: String
}

func fetchToken(cartId: String) async throws -> String {
    var request = URLRequest(url: URL(string: "https://api.yourshop.com/checkout")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try JSONEncoder().encode(["cart_id": cartId])

    let (data, _) = try await URLSession.shared.data(for: request)
    let decoder = JSONDecoder()
    decoder.keyDecodingStrategy = .convertFromSnakeCase
    return try decoder.decode(CheckoutResponse.self, from: data).authorizationToken
}

2. Présentez l'interface depuis un view controller. present se résout une seule fois, quand l'interface a disparu, avec la valeur que reçoit onComplete : un autre present peut suivre aussitôt. Appelé depuis onComplete, ou juste après la disparition de l'écran de présentation, il attend que l'interface réglée ait disparu ; seule une interface encore ouverte lui fait lever sheet_already_presented.

import UIKit
import WajubMobile
import WajubMobileUI

@MainActor
func pay(token: String, from viewController: UIViewController) async {
    var options = PresentOptions(sessionToken: token)
    options.returnURL = "https://shop.example.com/app/return" // optional, a universal link into your app
    options.callbacks.onStateChange = { event in print("checkout:", event.state.rawValue) }

    do {
        switch try await WajubCheckout.present(options, from: viewController) {
        case .complete(let payment, _):
            // Paid. Confirm on your server before delivering.
            await confirmOnServer(paymentId: payment.id)
        case .processing:
            // Closed while a payment was running: money may still move.
            showPending()
        case .failed(let error, _):
            showError(error.message)
        case .cancelled(let reason, _):
            print("cancelled:", reason.rawValue)
        }
    } catch let error as WajubError {
        // Only sheet_already_presented: a sheet is already open.
        print(error.code)
    } catch {}
}

from: est facultatif. Sans lui, l'interface se présente depuis le view controller le plus haut de la fenêtre principale. Il n'existe ni vue ni modificateur SwiftUI pour l'interface : depuis un écran SwiftUI, appelez WajubCheckout.present sans from:, ou avec le view controller qui héberge votre vue.

3. Confirmez sur votre serveur avant toute livraison, avec GET /payments/{id} ou le webhook payment.succeeded. Le résultat dans l'application est ce que le payeur a vu, pas une preuve de paiement : une approbation Mobile Money peut arriver après la fermeture de l'interface.

Options

PresentOptions est une structure de propriétés var. Son initialiseur les prend toutes en arguments nommés, avec les valeurs par défaut ci-dessous : réglez-les là, ou sur la valeur ensuite.

let options = PresentOptions(
    sessionToken: token,
    locale: "fr",
    loader: .spinner,
    returnURL: "https://shop.example.com/app/return",
    mobileMoney: MobileMoneyOptions(country: "CI", countryLocked: true, operatorMode: .detect),
    realtime: RealtimeOptions(host: "ws.shop.example", port: 443, tls: true),
    cancelOnDismiss: false
)

LoaderStyle(wajubJS:) lit la valeur loader d'une configuration Wajub.js : "skeleton" donne .skeleton, toute autre valeur, "none" comprise, donne .spinner.

Callbacks et états

Chaque callback est facultatif et appelé sur le thread principal, dans cet ordre : onReady, puis onStateChange au fil des écrans, onPaymentStarted et onRedirect, puis onSuccess, onError ou onCancel, et onComplete une seule fois. Chacun est typé (@MainActor (Payload) throws -> Void)? : un callback qui lève une erreur est intercepté et journalisé, et l'interface continue.

options.callbacks = CheckoutCallbacks(
    onReady: { event in print("ready:", event.environment, event.methods) },
    onPaymentStarted: { event in print("paying with", event.channel) },
    onError: { error in print(error.code, error.correlationId ?? "-") }
)

CheckoutState est une énumération String dont les valeurs brutes sont les 17 noms de Wajub.js : .initiated (INITIATED), .collectingDetails, .processing, .approvalRequired, .ussdRequired, .otpRequired, .pinRequired, .phoneRequired, .birthdayRequired, .addressRequired, .threeDSRequired (3DS_REQUIRED), .verifying, .pending, .success, .failed, .expired et .cancelled. Comparez sur le cas, journalisez rawValue. Ce que montre chaque état est décrit sur SDKs mobiles.

Résultats

CheckoutResult est une énumération à quatre cas, et status donne son nom sous forme de chaîne, complete, processing, failed ou cancelled.

PaymentSuccess est celui de Wajub.js : 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.

present se résout quoi qu'il arrive à l'écran depuis lequel vous l'avez présentée. Quand cet écran est fermé ou désalloué pendant que l'interface est ouverte, elle se résout en .cancelled avec .hostGone avant toute tentative, en .processing une fois une tentative lancée et en .complete après un succès, sans jamais annuler le paiement. Sans fenêtre depuis laquelle se présenter, ou si UIKit refuse la présentation, elle se résout aussitôt en .hostGone.

Si le processus de l'application meurt, rien ne peut se résoudre. Au lancement suivant, lisez le résultat sur votre serveur, ou avec WajubSession(sessionToken:).status().

Ouverture et paiements sans réponse

• Un paiement qui n'est pas pending à l'ouverture est dessiné aussitôt à partir de la session, sans attendre la configuration des moyens de paiement (GET /pay/sdk-config) : l'écran de succès s'il est payé, un avis « Ce paiement est terminé » avec onLoadError s'il a échoué, a été annulé ou a expiré, et l'écran d'approbation ou d'attente où il en était, suivi, s'il est encore processing.
• Quand la configuration des moyens de paiement ne peut pas être lue, le Mobile Money reste proposé. Si rien ne peut l'être sans elle, une carte ou un portefeuille seulement, l'interface signale load_error, qu'on peut réessayer, plutôt que no_payment_method.
• Une requête de paiement restée sans réponse, un 5xx compris, n'est jamais affichée comme un échec : l'interface affiche « Paiement en cours » et suit le paiement. Un refus plus récent que la tentative s'affiche aussitôt. Si le paiement n'a toujours pas commencé 60 secondes après le dernier essai, l'interface revient au formulaire avec une erreur de connexion, et le Payer suivant envoie la même Idempotency-Key.
• Un 400 fait lire le statut : une issue s'affiche, un paiement processing ou un statut illisible est suivi, et un paiement encore pending échoue avec not_processable.
• Le suivi s'arrête 15 minutes après l'appui sur Payer, mesurées sur l'horloge monotone du téléphone, quoi que disent son heure ou l'expiration du paiement.

Les règles complètes sont sur SDKs mobiles.

Annuler et fermer

Le payeur ferme l'interface avec son bouton de fermeture ou d'un glissement vers le bas. Pendant une requête (un paiement, une vérification, une annulation, votre collecteur de carte), l'interface ne peut pas être glissée vers le bas.

L'interface n'annule qu'un paiement chargé, dont le dernier statut connu est pending, sans tentative non tranchée. Une tentative n'est pas tranchée de l'appui sur Payer jusqu'à une réponse définitive : un refus, une étape ou un 3-D Secure échoués pour de bon, une session carte refusée, ou un statut pending avec un nouveau code de refus. Après un tel refus, le paiement est de nouveau pending et peut être annulé.

Annuler le paiement est proposé sur la liste des moyens, sur un formulaire et sur un échec que le payeur peut réessayer, jamais pendant une tentative non tranchée. Il annule le paiement définitivement et donne .cancelled avec .payerCancelled. Une annulation que l'API refuse lit le statut du paiement et se résout avec ce qu'il indique. Les règles complètes sont sur SDKs mobiles.

Apparence

PresentOptions.appearance prend l'objet d'apparence de Wajub.js 1.8, clé pour clé : vos Components web et l'interface native partagent un même style.

options.appearance = Appearance(
    theme: .stripe,              // presets: .stripe, .night, .flat, .noPreset
    colorScheme: .auto,          // .light, .dark, .auto (follows the phone, live)
    variables: AppearanceVariables(
        colorPrimary: "#0F766E",
        fontFamily: "Poppins",   // used when your app ships it
        borderRadius: "12px"
    ),
    buttonTextColor: "#FFFFFF"
)

• Les arguments suivent l'ordre de déclaration des initialiseurs, comme Swift l'exige : dans AppearanceVariables, fontFamily vient avant borderRadius.
• Le "none" de Wajub.js s'écrit .noPreset pour theme et .noShadow pour shadow : aucun des deux ne peut se lire comme le none du type optionnel.
• Les clés sont celles de Wajub.js : theme, colorScheme, inherit, variables (seize jetons de design, de colorPrimary à spacingGridColumn) et les clés de premier niveau primaryColor, secondaryColor, backgroundColor, fontFamily, borderRadius, buttonTextColor, inputBackgroundColor, inputBorderColor, textMutedColor, successColor, errorColor, shadow, labels et disableAnimations. Les valeurs sont des chaînes, comme sur le web, et une valeur illisible est ignorée.
• L'objet que votre checkout web utilise déjà se lit tel quel : Appearance(json: try JSONValue.parse(jsonString)). Les clés inconnues, rules compris, sont ignorées.
• inherit: true lit l'écran de présentation : sa tintColor comme couleur principale, systemBackground, label, secondaryLabel et separator résolues pour son apparence, et son style clair ou sombre. Une couleur n'est gardée que si elle contraste assez avec le fond.
• Pour chaque jeton, la première valeur définie l'emporte : variables, les clés de premier niveau, le préréglage, la valeur héritée, l'image de marque du marchand dans le Dashboard, puis la palette par défaut de Wajub.
• L'image de marque du marchand complète ce que vous laissez vide : les couleurs, l'arrondi, la police (utilisée seulement si votre application l'embarque), et le logo et le nom commercial dans l'en-tête. Un marchand en marque blanche masque « Sécurisé par Wajub ».
• disableAnimations: true, ou Réduire les animations sur le téléphone, arrête la pulsation du squelette et les fondus.

Les règles du schéma de couleurs et les palettes par défaut sont sur SDKs mobiles, les clés elles-mêmes sur Apparence.

Mobile Money

Un seul formulaire couvre tous les opérateurs : le pays, le numéro avec son indicatif, mis en forme pendant la saisie, et les opérateurs de la session, un agrégat comme cm.mobile présentant un opérateur par ligne. L'opérateur auquel appartient le numéro est présélectionné tant que le payeur n'en a pas choisi un lui-même, et un numéro d'un autre opérateur proposé est refusé avant tout appel. Wave et les autres portefeuilles qui acceptent n'importe quel numéro ne sont jamais refusés. Le numéro part au format E.164, et la Côte d'Ivoire garde son 0 initial.

Après Payer, l'interface affiche « Validez le paiement sur votre téléphone » avec le numéro et l'instruction de l'opérateur, puis suit le paiement jusqu'à son issue.

Les logos des opérateurs se chargent depuis leur URL https. Un logo absent ou qui ne se charge pas comme une image, un SVG par exemple, est remplacé par le badge de la marque de l'opérateur.

Pour vos propres écrans, MobileMoneyData.shared expose les mêmes règles : nationalDigits(_:country:), isValid(_:country:), detectOperator(_:country:), e164(_:country:), formatAsYouType(_:) et badge(operatorId:fallbackName:). Le comportement commun à tous les SDKs est sur SDKs mobiles.

Cartes

Le prestataire derrière le canal carte décide de l'écran. L'interface le lit dans la configuration SDK de la session.

Un portefeuille en un geste comme Djamo, et une page Mobile Money comme celle de Wave, est confié à iOS avec UIApplication.open, qui ouvre l'application du portefeuille. Au retour du payeur, Safari fermé ou l'application revenue au premier plan, l'interface lit aussitôt le statut du paiement. Tant qu'une page est ouverte ailleurs, « Continuer le paiement » la rouvre.

Stripe par votre propre collecteur

Seul le SDK de Stripe peut créer un pm_… Stripe, et le package ne dépend pas de stripe-ios. Implémentez CardCollector dans votre application : l'interface l'appelle quand le payeur touche Payer par carte, puis envoie le pm_… qu'il renvoie.

import StripePaymentsUI
import WajubMobile

final class StripeCardCollector: CardCollector {
    @MainActor
    func collectPaymentMethod(_ request: CardCollectionRequest) async throws -> String? {
        STPAPIClient.shared.publishableKey = request.publishableKey
        // CardEntryScreen is your own screen with an STPPaymentCardTextField, presented over the sheet.
        guard let card = await CardEntryScreen.present(amount: request.amount, currency: request.currency) else {
            return nil // the payer backed out
        }
        let paymentMethod = try await STPAPIClient.shared.createPaymentMethod(with: card.paymentMethodParams)
        return paymentMethod.stripeId
    }
}

options.cardCollector = StripeCardCollector()

CardCollectionRequest contient publishableKey (la clé Stripe propre au paiement, issue de la session), amount, currency, customerEmail, customerName et language, celle de l'interface. Renvoyez nil quand le payeur renonce : l'interface reste sur le formulaire carte et rien n'est débité. Une erreur levée s'affiche sur le formulaire carte : une WajubError telle quelle, toute autre erreur comme validation_error, avec la description propre à l'erreur quand elle en a une (celles de Stripe en ont), sinon « Vérifiez les informations saisies. », et son texte conservé dans apiMessage. Dès le toucher sur Payer par carte, une fermeture donne .processing, et rien n'est envoyé une fois l'interface fermée.

Étapes de confirmation

Certains prestataires de carte demandent davantage au payeur après le premier envoi. Chaque étape a son écran, avec les essais restants dans l'erreur après une mauvaise réponse et « Renvoyer le code » proposé 60 secondes après l'ouverture de l'écran.

Un mauvais code garde l'écran. Une étape expirée ou à court d'essais se termine sur l'écran d'échec, et Réessayer ramène au choix d'un moyen de paiement. Les codes sont sur SDKs mobiles.

Erreurs

Chaque échec est une WajubError, une structure conforme à Error et LocalizedError, dont errorDescription est message.

toJSON() donne la forme du contrat, avec des clés en snake_case.

case .failed(let error, _):
    switch error.code {
    case WajubError.Code.insufficientFunds:
        showError(error.message) // retryable: another number or method
    case WajubError.Code.shieldBlocked:
        showError(error.message) // carries error.blockReference
    default:
        showError(error.message)
    }

Les codes que vous rencontrerez : insufficient_funds, payment_declined, payment_attempt_ended (refusé, rien n'a été débité), payment_failed, shield_blocked, merchant_restricted, rate_limited, session_terminal_expired, unsupported_action, redirect_unavailable, security_check_failed. Le catalogue complet, avec ses messages anglais et français, est sur SDKs mobiles.

Votre propre interface

WajubMobile vous donne le client de l'API et la machine à états de l'interface, pour une application qui dessine ses propres écrans de paiement.

WajubSession(sessionToken:language:) est le client bas niveau. Il envoie les en-têtes, les signaux de l'appareil, les délais, les nouvelles tentatives et la Idempotency-Key du contrat, et renvoie les formes de l'API.

import WajubMobile

func payHeadless(token: String) async throws {
    let session = WajubSession(sessionToken: token)
    let payment = try await session.session()
    print(payment.transaction.amountTotal, payment.channels.map(\.slug))

    let outcome = await session.process(
        channel: "cm.mobile",
        data: ["phone": "+237677123456", "country": "CM", "operator": "mtn"]
    )
    switch outcome {
    case .complete(let transaction):
        print("paid", transaction.id)
    case .processing(_, let instruction, let kind):
        // .approval, .ussd or .pending: follow GET /pay/status, never show a failure.
        print(kind, instruction ?? "")
    case .requiresAction(let required):
        if required.action == .confirmOTP, let stepId = required.stepId {
            let answer = try await session.verify(.otp, id: stepId, fields: ["code": "123456"])
            print(answer)
        }
    case .failed(let error, _):
        print(error.code, error.message)
    }
}

process génère une nouvelle Idempotency-Key sauf si vous en passez une, et ses nouvelles tentatives automatiques la réutilisent. Une réponse jamais arrivée, ou un 5xx, revient en .processing de type .pending : suivez le statut, n'affichez jamais un échec.

Checkout.present(_:presenter:browser:) exécute tout le checkout sous votre propre interface, avec les mêmes règles que WajubCheckout.present : une seule interface à la fois, et un résultat une fois votre interface disparue. Il crée le CheckoutController, l'automate de l'interface, à partir de vos options, le confie à CheckoutPresenting.present(_:), le démarre, puis, une fois le checkout réglé, appelle votre dismiss(_:completion:) et se résout avec le CheckoutResult.

• Votre présentateur dessine le screen du contrôleur (un CheckoutScreen), avec state, methods, mobileMoney, cardForm, fieldErrors, banner et le reste, redessine sur onChange, et relie vos boutons à ses actions : selectMethod, setPhone, pickOperator, submitMobileMoney, setCardField, submitCard, payWallet, submitStep, submitThreeDSCode, continuePayment, tryAgain, cancelPayment, dismiss, appWillEnterForeground, hostGone et les autres. Si votre interface ne peut pas s'afficher, appelez controller.hostGone(). Appelez la completion de dismiss une fois votre interface disparue.
• Votre BrowserOpening ouvre les pages des prestataires : .inApp (pages carte, 3-D Secure, sessions client) dans un SFSafariViewController, en appelant onClose à sa fermeture, et .external (la page d'un portefeuille) avec UIApplication.open. Il renvoie false quand rien ne peut ouvrir la page.
• completion et onClose sont tous deux @MainActor @Sendable : ils peuvent passer dans les gestionnaires de fin du système dans une application Swift 6.

import Foundation
import WajubMobile

@MainActor
final class MySheet: CheckoutPresenting {
    private var controller: CheckoutController?

    func present(_ controller: CheckoutController) {
        self.controller = controller
        controller.onChange = { [weak self] in self?.render() }
        // Show your sheet; its buttons call the controller's actions.
    }

    func dismiss(_ controller: CheckoutController, completion: @escaping @MainActor @Sendable () -> Void) {
        // Hide your sheet, then:
        self.controller = nil
        completion()
    }

    private func render() {
        guard let controller else { return }
        print(controller.state?.rawValue ?? "loading") // draw controller.screen
    }
}

@MainActor
final class MyBrowser: BrowserOpening {
    func open(_ url: URL, mode: BrowserMode, onClose: @escaping @MainActor @Sendable () -> Void) async -> Bool {
        // .inApp: present an SFSafariViewController and call onClose() once it is closed.
        // .external: return await UIApplication.shared.open(url).
        false // nothing could open the page
    }
}

@MainActor
func payWithMySheet(_ options: PresentOptions) async throws -> CheckoutResult {
    try await Checkout.present(options, presenter: MySheet(), browser: MyBrowser())
}

Sans Checkout, vous pouvez aussi créer vous-même CheckoutController(options:browser:), définir son onChange et son onFinish, qui reçoit le CheckoutResult une seule fois, quand votre interface doit se fermer, et appeler start().

Confidentialité

Pour évaluer la fraude comme le fait le checkout web, chaque POST /pay/process envoie à Wajub quelques signaux de l'appareil, et chaque appel nomme le SDK.

• Le fuseau horaire, la première langue préférée et les langues (Accept-Language), la taille de l'écran principal en pixels et une profondeur de couleur de 24.
• Le SDK et le système, wajub-ios/1.0.0 (ios 18.1), dans X-Wajub-Client et à la fin du User-Agent, après le nom et la version de votre application.
• Une empreinte d'installation : le SHA-256 d'un identifiant aléatoire que le SDK crée à la première utilisation. Elle ne dérive d'aucun identifiant matériel ou publicitaire. Elle est conservée dans un fichier du dossier Application Support de l'application, com.wajub.mobile/install-id, exclu des sauvegardes, et disparaît avec l'application quand elle est désinstallée.

WajubMobile fournit un manifeste de confidentialité, PrivacyInfo.xcprivacy, qu'Xcode ajoute au rapport de confidentialité de votre application (Product › Archive, puis Generate Privacy Report dans l'Organizer). Il déclare :

• Aucun suivi, et aucun domaine de suivi.
• Une seule API à raison requise, le temps depuis le démarrage du système (ProcessInfo.systemUptime), avec la raison 35F9.1 : elle mesure les attentes du SDK sur le téléphone et ne le quitte jamais. Aucun UserDefaults : l'identifiant d'installation est le fichier ci-dessus.
• Les données collectées, toutes liées à l'utilisateur, non utilisées pour le suivi, pour le fonctionnement de l'app (App Functionality) : nom, adresse e-mail, numéro de téléphone, adresse postale, informations de paiement, identifiant de l'appareil et autres données.

Le manifeste ne remplit pas App Store Connect à votre place. Déclarez ce que le SDK envoie à Wajub, votre prestataire de paiement, sous App Privacy, comme des données que collecte votre application, liées à l'identité de l'utilisateur, non utilisées pour le suivi, pour App Functionality, avec ce que votre application collecte elle-même.

Un numéro de carte saisi sur la page d'un prestataire dans Safari va à ce prestataire, sans passer par le SDK. Les signaux qu'envoient tous les SDKs sont sur SDKs mobiles.

Avant 1.0

Il n'existe aucune version antérieure depuis laquelle migrer. Jusqu'à ce package, une application iOS encaissait un paiement Wajub par le checkout hébergé dans Safari, ou par le SDK Flutter ou React Native.

Passer une application native à l'interface de paiement ne change rien sur votre serveur. POST /payments renvoie le authorization_token que prend l'interface à côté du authorization_url qu'ouvre le checkout hébergé, et le même webhook payment.succeeded confirme le paiement.

Tests

L'origine de l'API est une constante, il n'y a donc aucune URL de base à rediriger. Un paiement que votre serveur crée avec une clé sandbox place tout le parcours en sandbox, interface comprise, et l'interface affiche « Mode test ».

• Les numéros Mobile Money de test sont un préfixe d'opérateur et sept chiffres finissant par le scénario : 000000 succès, 000001 fonds insuffisants, 000002 échec, 000003 délai dépassé, 000004 annulé, +237670000000 par exemple. Les préfixes de la sandbox ne suivent pas les plans de numérotation réels : l'interface s'y contente d'avertir d'un opérateur qui ne correspond pas.
• Le formulaire carte accepte les cartes de test de Wajub, et 4000056655665556 demande le code 3-D Secure envoyé par e-mail.

Tous les numéros et toutes les cartes sont sur Scénarios de test.