Intégration dans les apps mobiles

Les apps natives et hybrides utilisent le même checkout FlowAlp Pay hébergé que le web. Le schéma repose sur deux briques : votre backend crée le paiement et l'app affiche le lien de paiement dans une WebView ou un navigateur in-app, puis des deep links ramènent le client dans l'app.

Flux recommandé#

1. Votre backend crée un Gateway avec montant, devise, referenceId et URL de redirection — l'API Secret n'est jamais embarqué dans l'app.
2. L'app ouvre le lien de paiement renvoyé dans une WebView ou, de préférence pour les wallets et 3-D Secure, dans le composant navigateur du système (SFSafariViewController sur iOS, Custom Tabs sur Android).
3. Le client termine le paiement sur la page hébergée.
4. La redirection succès, échec ou annulation le ramène — faites pointer ces URL vers des deep links appartenant à votre app.
5. L'app interroge votre backend sur l'état de la commande ; le backend l'a confirmé via webhook ou récupération API.

Créer le Gateway avec des URL de retour deep link#

curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/" \
  --header "Content-Type: application/json" \
  --header "x-api-key: ${FLOWALP_API_SECRET}" \
  --data '{
    "instance": "tenantname",
    "amount": 8925,
    "currency": "CHF",
    "referenceId": "ORDER-975382",
    "successRedirectUrl": "https://app.example.com/pay/success",
    "failedRedirectUrl": "https://app.example.com/pay/failed",
    "cancelRedirectUrl": "https://app.example.com/pay/cancel"
  }'

Préférez les Universal Links (iOS) et App Links (Android) aux schémas d'URL personnalisés : le système d'exploitation les valide contre votre domaine et bascule sur le navigateur si l'app est absente. Considérez les trois URL de retour comme de la pure navigation — atteindre l'URL de succès ne prouve pas le paiement.

Écouter les événements de paiement dans la WebView#

Quand la page de paiement s'exécute dans une page hébergée en WebView, elle signale sa progression via postMessage, exactement comme décrit dans le guide iFrame. Envoyez le handshake d'origin une fois la page chargée, puis surveillez l'événement transaction.

window.addEventListener('message', function (event) {
  if (typeof event.data !== 'string') return;
  var data = null;
  try { data = JSON.parse(event.data); } catch (ignore) { return; }
  if (!data || typeof data !== 'object') return;

  // Events arrive wrapped under a single vendor namespace key
  Object.keys(data).forEach(function (key) {
    var events = data[key] || {};
    if (events.transaction && typeof events.transaction === 'object') {
      if (events.transaction.status === 'confirmed') {
        // UI signal only - your backend must confirm via webhook or API
      } else {
        // Show a failure or retry state
      }
    }
  });
});

Dans les WebViews de type React Native, injectez un petit listener qui transmet les messages de window à la coque de l'app et traitez-les dans le gestionnaire de messages de l'app. Attention à la différence de plateforme pour le handshake d'origin : injectez-le avant le chargement du contenu sur Android, envoyez-le après la fin du chargement sur iOS.

Moyens avec changement d'app : TWINT et wallets#

Certains moyens de paiement quittent votre app pendant le paiement : TWINT bascule vers sa propre app sur le même appareil, Apple Pay et Google Pay ouvrent les feuilles du système. Vérifiez que votre composant navigateur autorise l'ouverture d'apps externes et revient proprement au checkout. Les moyens affichés dépendent de la configuration de votre compte — voir moyens de paiement.

Confirmer côté serveur avant de livrer#

Retours par deep link, événements WebView et écrans de succès peuvent être falsifiés ou perdus. N'exécutez une commande qu'après réception du webhook par votre backend — avec vérification de signature — ou après récupération de la transaction via l'API. Traitez annulation et timeout comme des états distincts.

Tester sur des appareils réels#

• Déroulez les scénarios succès, échec, annulation et checkout abandonné sur des appareils iOS et Android physiques.
• Vérifiez l'aller-retour deep link pour chaque moyen de paiement proposé, y compris ceux avec changement d'app.
• Utilisez le mode TEST et les cartes de test avant de débiter de l'argent réel.