iFrame-Embedding

Mit dem iFrame-Embedding erscheint das FlowAlp Pay Zahlungsformular direkt in Ihrer Website statt auf einer separaten Seite. Einbetten können Sie eine im Dashboard konfigurierte Zahlungsseite, das virtuelle Terminal oder den Zahlungslink eines per API erstellten Gateways.

Die richtige URL wählen#

<instance> ist Ihr Instanzname; der Wert tid ist die ID einer mit dem Pages-Tool im Dashboard erstellten Zahlungsseite.

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

530 Pixel Breite und 700 Pixel Höhe sind bewährte Startwerte; mit den Resize-Events unten passt sich die Höhe dynamisch an.

Wallet-Unterstützung: das allow-Attribut#

Behalten Sie das Attribut allow="payment *" auf dem Frame bei — Google Pay funktioniert nur damit. Ohne das Attribut erscheint der Wallet-Button im eingebetteten Formular nicht.

Methoden, die nicht im iFrame laufen#

Aus Sicherheitsgründen verweigern einige Zahlungsmethoden die eingebettete Ausführung, darunter PostFinance Pay, Reka Pay, PayPal und Coinbase. PostFinance wird zusätzlich deaktiviert, wenn der Browser Drittanbieter-Cookies blockiert — Standard auf iOS und macOS.

Damit solche Methoden verfügbar bleiben, hängen Sie den GET-Parameter &breakIframe=true an die eingebettete URL an. Die betroffene externe Zahlungsseite öffnet sich dann in einem neuen Browser-Tab statt im Frame.

Auf Events der Zahlungsseite reagieren#

Die eingebettete Seite kommuniziert per postMessage mit Ihrer Website. Zwei Schritte: Nach dem Laden des iFrames senden Sie einen Handshake mit Ihrer Origin, damit die Seite antworten darf; danach sendet die Seite JSON-kodierte Nachrichten mit folgenden Events.

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;
    }
  });
});

Setzen Sie den Parameter appview nicht auf die eingebettete URL, wenn Sie die dynamische Höhe nutzen möchten — beides schliesst sich gegenseitig aus.

Zahlung serverseitig bestätigen#

Legen Sie den API Secret nie ins Frontend und markieren Sie eine Bestellung nie als bezahlt, nur weil das transaction-Event einen Erfolg meldet. Bestätigen Sie den finalen Status über Webhooks mit Signaturprüfung oder rufen Sie die Transaktion über die API ab.