SDKs mobiles

Une architecture, trois packages et une interface de paiement native sans WebView.

Les trois SDKs mobiles reposent sur la même conception dans trois langages. Votre serveur crée le paiement et transmet un authorization_token à l'application. Celle-ci crée une session à partir du jeton et affiche une interface native. Le payeur ne quitte jamais votre application.

Ce parcours n'utilise aucune WebView, c'est tout son intérêt. Les champs Mobile Money sont natifs. Les champs de carte utilisent les composants natifs de Stripe quand Stripe porte la carte ; avec un autre prestataire, la carte est saisie sur la page de ce prestataire, qui s'ouvre dans le navigateur du système, comme une vérification 3DS ou une redirection bancaire.

Les trois packages

Plateforme	Package	Registre	Version
Flutter	`wajub_mobile`	pub.dev	1.1.1
React Native	`@wajub/react-native`	npm	1.1.1
Android	`com.wajub:wajub-mobile-core`	Maven Central	1.2.1
Android	`com.wajub:wajub-mobile-compose`	Maven Central	1.2.1

Ces pages décrivent Flutter et React Native 1.4.0 et Android 1.2.0. Sur une version 1.1, une carte dont le prestataire n'est pas Stripe apparaît comme indisponible et les portefeuilles en un geste sont absents : mettez à jour avant de compter sur l'un ou l'autre.

Il n'existe aucun package Swift

Wajub ne propose aucun SDK iOS natif. Une application Swift accède à Wajub grâce au checkout hébergé dans un SFSafariViewController, ou avec Flutter ou React Native. Consultez Choisir votre SDK pour comparer ces possibilités.

Le flux en une fois

Les trois SDKs suivent ces cinq étapes. Vous devez uniquement concevoir celle du milieu.

Lieu d'exécution de chaque partie

Your server                          Your app
───────────                          ────────
POST /payments with sk.
  returns authorization_token  ──▶   createSession(token)
                                       │
                                       ├─ loads the session and its channels
                                       ├─ shows the sheet you chose
                                       └─ processes the payment natively
                                           │
webhook payment.succeeded     ◀──────────┘
  fulfils the order

Le jeton est le seul identifiant détenu par l'application. Il est limité à un paiement, expire et ne permet pas de lister, de rembourser ou de lire quoi que ce soit d'autre sur votre compte. Votre clé secrète reste sur votre serveur.

Les mêmes canaux que le checkout hébergé

L'interface de paiement propose les mêmes canaux et opérateurs que la page de checkout hébergé, et se comporte de la même façon. Le SDK accède à Wajub avec le seul jeton de session : il n'a jamais besoin de vos clés.

Les tentatives de paiement sont limitées

Les tentatives de paiement sur une session sont limitées. Ne les placez pas dans une boucle de nouvelles tentatives : sur une rateLimitError, attendez retryAfterSeconds avant de proposer un nouvel essai au payeur.

Choisir l'interface

Chaque SDK propose deux niveaux. L'interface de paiement est la solution rapide. Utilisez les méthodes de session si le paiement doit s'intégrer à votre propre design.

Votre objectif	Solution
Un paiement fonctionnel dès maintenant	L'interface de paiement fournie
Vos propres écrans et votre image de marque	Les méthodes de session, `payMobileMoney`, `payCard` et les autres ci-dessous
Afficher le montant avant le paiement	`loadSession()`, puis l'affichage de votre choix
Un statut en direct pendant la confirmation du payeur	`watchStatus()`

Le parcours carte qu'une session obtient

Le prestataire derrière le canal en décide, et getSdkConfig() indique lequel. L'interface de paiement le lit et affiche le bon écran ; avec vos propres écrans, vous appelez la méthode correspondante.

Ce que `getSdkConfig()` renvoie pour le canal	Ce qui se passe	Méthode de session
`stripe_elements`	Les champs de carte natifs de Stripe, tokenisés sur l'appareil	`payCard`
`client_session` vaut vrai, Paystack ou Flutterwave par exemple	Le checkout hébergé du prestataire s'ouvre dans le navigateur du système, et il est vérifié au retour du payeur	`startClientSession`, puis `completeClientSession`
`hosted_redirect`, PayPal, Kkiapay, FedaPay ou CinetPay par exemple	La page carte du prestataire, après les champs de contact qu'il liste dans `required_fields`	`payCardHostedRedirect`
Un canal `wallet` sans champ requis, Djamo par exemple	Une redirection qui ouvre l'application du portefeuille	`payWallet`

Une étape que le SDK ne peut pas réaliser nativement, un OTP saisi dans votre propre écran par exemple, revient comme un résultat en échec avec le code unsupported_action, jamais comme un paiement laissé en cours indéfiniment.

Temps réel ou polling

watchStatus() reçoit le résultat en temps réel quand c'est possible, et interroge Wajub toutes les cinq secondes sinon. Votre code l'appelle de la même façon dans les deux cas, sans avoir à choisir.

À partir de React Native 1.4.1, d'Android 1.2.1 et de Flutter 1.5.0, ce polling tourne dans les deux cas, à côté de la connexion temps réel : un événement manqué coûte au plus un intervalle.

Le webhook reste responsable de la livraison de la commande

Une confirmation Mobile Money peut arriver après la fermeture de l'application par le payeur. Le téléphone peut aussi perdre le réseau pendant l'approbation. Utilisez le résultat de l'interface pour choisir l'écran à afficher et le webhook pour livrer les biens.

Montants et erreurs sont également partagés

Les montants utilisent partout l'unité principale. Ainsi, 25000 en XAF correspond à vingt-cinq mille francs. Le type d'erreur est la même union de cinq possibilités dans les trois SDKs.

Type d'erreur	Signification
`authenticationError`	Le jeton a expiré, a déjà été utilisé ou est inconnu
`invalidRequestError`	Le canal a refusé un champ, identifié par `param`
`paymentError`	Le prestataire a refusé le paiement, `declineCode` indique la raison
`rateLimitError`	Trop de tentatives, `retryAfterSeconds` indique le délai d'attente
`apiError`	Erreur côté Wajub ou problème réseau

Chaque erreur contient retryable, qui détermine s'il faut proposer une nouvelle tentative au payeur.

Une session terminée (410) est une authenticationError non réessayable, et une erreur serveur (5xx) une apiError, à partir de React Native 1.4.1, Android 1.2.1 et Flutter 1.5.0. Les versions précédentes renvoyaient les deux comme une paymentError réessayable. Un jeton qui n'est pas une session (401, 404) n'est pas réessayable non plus, dans les mêmes versions.

Choisir votre plateforme

Pages associées