React Native

Le SDK React Native 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. present() l'ouvre et se résout une fois, à sa fermeture.

Installer

npm install @wajub/react-native @react-native-community/netinfo @react-native-async-storage/async-storage

npm install @stripe/stripe-react-native

cd ios && pod install

@stripe/stripe-react-native impose ses propres versions minimales d'iOS et d'Android, qui deviennent les vôtres dès que vous l'installez. Aucun provider n'est nécessaire à la racine de votre application : usePayment() fonctionne dans n'importe quel composant.

Démarrage rapide

1. Votre serveur crée le paiement avec sa clé secrète et transmet authorization_token à l'application.
2. L'application appelle present() avec ce jeton. Affichez l'élément PaymentSheet que le hook renvoie dans le même composant.
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 { Button } from 'react-native';
import { usePayment } from '@wajub/react-native';

function CheckoutScreen({ authorizationToken }: { authorizationToken: string }) {
  const { present, PaymentSheet } = usePayment();

  const pay = async () => {
    const result = await present({
      sessionToken: authorizationToken,
      returnUrl: 'https://shop.example.com/app/payment-return', // optional, a universal/app link
    });

    switch (result.status) {
      case 'complete':
        // Paid on the device. Deliver once your server has confirmed it.
        return showReceipt(result.payment.id);
      case 'processing':
        // Closed while a payment was running: an approval may still land.
        return showPending();
      case 'failed':
        return showError(result.error.message);
      case 'cancelled':
        // result.reason: 'payer_cancelled', 'dismissed' or 'host_gone'
        return;
    }
  };

  return (
    <>
      <Button title="Pay" onPress={pay} />
      {PaymentSheet}
    </>
  );
}

present() se résout exactement une fois, avec la valeur que reçoit onComplete. Si le composant qui a appelé le hook est démonté pendant que l'interface est ouverte, il se résout quand même : cancelled avec host_gone avant toute tentative, processing dès qu'une tentative a commencé, complete après un succès. Un appel pendant qu'une interface est ouverte est rejeté avec une WajubError de code sheet_already_presented, sans toucher à l'interface ouverte.

Options

Tout se passe dans l'unique objet que prend present(), callbacks de la section suivante compris.

Callbacks et états

Tous facultatifs, tous appelés sur le thread JavaScript, dans cet ordre pour un paiement : onReady, puis onStateChange à mesure que le payeur avance, onPaymentStarted et onRedirect quand ils s'appliquent, onSuccess, onError ou onCancel, et onComplete en dernier, une seule fois. Un callback qui lève une erreur est journalisé, et l'interface continue.

onStateChange signale l'un de ces états : INITIATED (liste des moyens), COLLECTING_DETAILS (le formulaire d'un moyen), PROCESSING (Payer pressé), APPROVAL_REQUIRED, USSD_REQUIRED, PAYER_OTP_REQUIRED (le code que génère le payeur), OTP_REQUIRED, PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED, ADDRESS_REQUIRED, 3DS_REQUIRED, VERIFYING, PENDING, SUCCESS, FAILED, EXPIRED et CANCELLED. L'écran derrière chacun est décrit dans SDKs mobiles.

Résultats

present() se résout avec l'un de quatre résultats. Faites un switch sur status.

PaymentSuccess contient id (l'identifiant de paiement de Wajub, 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: 'success', timestamp, et receipt_url quand il existe un reçu.

Une application tuée ne peut résoudre aucune promesse. Au lancement suivant, demandez le statut du paiement à votre serveur.

Annuler et fermer

Le payeur ferme l'interface avec ✕ dans son en-tête, le bouton retour d'Android, ou Fermer sur un écran final. Il n'y a pas de glissement vers le bas.

Annuler le paiement s'affiche sous la liste des moyens et sous les formulaires, jamais pendant qu'un paiement est en cours. Les règles sont dans SDKs mobiles.

Apparence

appearance règle l'aspect de l'interface : un préréglage, un mode de couleur et les valeurs que vous voulez changer.

await present({
  sessionToken,
  appearance: {
    theme: 'stripe', // a preset: 'stripe', 'night', 'flat', 'none'; or 'light', 'dark', 'auto', 'system'
    colorScheme: 'auto', // follows the phone, live
    variables: { colorPrimary: '#0F766E', borderRadius: '12px', fontFamily: 'Inter' },
    buttonTextColor: '#FFFFFF',
  },
});

• Mode de couleur : colorScheme vaut light, dark ou auto, qui suit le téléphone. inherit: true suit plutôt le mode de couleur de votre application.
• Image de marque : ce que vous laissez vide vient de l'image de marque du marchand dans le Dashboard, et un marchand en marque blanche masque « Sécurisé par Wajub ».
• Polices : fontFamily doit être une police que votre application embarque, sinon la police de la plateforme est utilisée.
• Libellés : labels: 'above', la valeur par défaut, place chaque libellé au-dessus de son champ ; 'floating' le place dans le champ vide.
• Mouvement : disableAnimations: true, ou le réglage de réduction des animations du téléphone, arrête les animations.

Chaque clé et chaque préréglage sont décrits dans Apparence.

Mobile Money

Un seul formulaire couvre tous les opérateurs Mobile Money du paiement : le payeur choisit le pays et l'opérateur et saisit le numéro, mis en forme pendant la saisie. Le préfixe du numéro présélectionne son opérateur, et un numéro d'un autre opérateur proposé est refusé avant tout envoi. Après Payer, « Validez le paiement sur votre téléphone » affiche le numéro et l'instruction de l'opérateur.

mobileMoney.country ouvre le formulaire sur un pays, countryLocked masque le sélecteur, et operatorMode: 'detect' garde la liste des opérateurs masquée tant que le numéro suffit à désigner l'opérateur. Plus de détails dans SDKs mobiles.

Cartes

Les cartes Stripe requièrent la dépendance homologue facultative @stripe/stripe-react-native ; aucune autre configuration Stripe n'est nécessaire. Si votre application encaisse aussi ses propres paiements Stripe, passez la clé de votre application dans stripe: { appPublishableKey } pour que vos propres paiements Stripe continuent de fonctionner.

Les autres cartes ouvrent une page sécurisée du prestataire de paiement dans le navigateur du système. En sandbox, l'interface affiche un formulaire de carte de test.

Étapes de confirmation

Quand un paiement demande une étape de plus après Payer, l'interface l'affiche en natif : un code à usage unique, le code PIN de la carte, un numéro de téléphone, une date de naissance ou une adresse de facturation, avec les essais restants après une mauvaise réponse. En sandbox, une carte qui demande 3-D Secure reçoit un code par e-mail. Les étapes et leurs états sont dans SDKs mobiles.

Erreurs

Chaque échec est une WajubError, une sous-classe d'Error. onLoadError, onError et un résultat failed en transmettent une. Ses champs sont en snake_case.

import { WajubError } from '@wajub/react-native';

try {
  const result = await present({
    sessionToken,
    onError: (error) => log('wajub', error.code, error.correlation_id),
  });

  if (result.status === 'failed') {
    // insufficient_funds, payment_attempt_ended, session_terminal_expired, ready_timeout…
    report(result.error.code, result.error.retryable);
  }
} catch (error) {
  if (error instanceof WajubError && error.code === 'sheet_already_presented') {
    // A sheet is already open.
  }
}

Les codes sur lesquels brancher votre code : 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 et sheet_already_presented. Chaque code est dans SDKs mobiles.

Votre propre interface

Les écrans de l'interface ne sont pas exportés. Une application qui dessine ses propres écrans de paiement utilise WajubSession, le client de plus bas niveau, que renvoie createSession(token) et que documente 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 les étiquettes de confidentialité de l'App Store et dans le formulaire de sécurité des données de Google Play, catégorie par catégorie, est sur SDKs mobiles.

Tests

Un paiement que votre serveur crée avec une clé de sandbox fait passer tout le parcours en sandbox, et l'interface affiche un badge « MODE TEST ». Les numéros et les cartes de test figurent dans Scénarios de test.