Intégration iFrame

Avec l'intégration iFrame, le formulaire de paiement FlowAlp Pay s'affiche directement dans votre site plutôt que sur une page séparée. Vous pouvez intégrer une page de paiement configurée dans le dashboard, le terminal virtuel ou le lien de paiement d'un Gateway créé via l'API.

Choisir l'URL à intégrer#

<instance> est votre nom d'instance ; la valeur tid est l'ID d'une page de paiement créée avec l'outil Pages du dashboard.

<iframe
  id="checkout-frame"
  src="https://<instance>.pay.flowalp.com/pay?tid=<PAYMENT_TEMPLATE_ID>"
  width="530"
  height="700"
  allow="payment *">
</iframe>

Une largeur de 530 et une hauteur de 700 pixels sont des valeurs de départ éprouvées ; avec les événements de redimensionnement ci-dessous, la hauteur s'ajuste toute seule.

Support des wallets : l'attribut allow#

Conservez l'attribut allow="payment *" sur le frame — Google Pay ne fonctionne que s'il est présent. Sans lui, le bouton du wallet n'apparaît pas dans le formulaire intégré.

Moyens de paiement incompatibles avec l'iFrame#

Pour des raisons de sécurité, certains moyens de paiement refusent l'exécution intégrée, notamment PostFinance Pay, Reka Pay, PayPal et Coinbase. PostFinance est en outre désactivé lorsque le navigateur bloque les cookies tiers, ce qui est le comportement par défaut sur iOS et macOS.

Pour garder ces moyens disponibles, ajoutez le paramètre GET &breakIframe=true à l'URL intégrée. La page de paiement externe concernée s'ouvre alors dans un nouvel onglet au lieu du frame.

Réagir aux événements de la page de paiement#

La page intégrée communique avec votre site via postMessage. Deux étapes : après le chargement de l'iFrame, vous envoyez un handshake contenant votre origin afin que la page soit autorisée à répondre ; ensuite la page envoie des messages JSON avec les événements suivants.

var frame = document.getElementById('checkout-frame');

// Handshake: tell the embedded page which origin may receive its events
frame.addEventListener('load', function () {
  frame.contentWindow.postMessage(
    JSON.stringify({ origin: window.location.origin }),
    frame.src
  );
});

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.height) {
      frame.style.height = parseInt(events.height, 10) + 'px';
    }
    if (events.top !== undefined) {
      window.scrollTo({
        top: frame.offsetTop + parseInt(events.top, 10),
        behavior: 'smooth'
      });
    }
    if (events.transaction && typeof events.transaction === 'object') {
      // UI signal only - fulfil orders after webhook or API confirmation
      console.log('Transaction status:', events.transaction.status);
    }
    if (events.closeModal) {
      window.location.href = events.closeModal;
    }
  });
});

N'ajoutez pas le paramètre appview à l'URL intégrée si vous utilisez la hauteur dynamique — les deux s'excluent mutuellement.

Confirmer le paiement côté serveur#

N'exposez jamais votre API Secret dans le frontend et ne marquez jamais une commande comme payée simplement parce que l'événement transaction annonce un succès. Confirmez l'état final via les webhooks avec la vérification de signature, ou récupérez la transaction via l'API.