Embedding iFrame

Con l'embedding iFrame il modulo di pagamento FlowAlp Pay compare direttamente nel tuo sito invece che su una pagina separata. Puoi incorporare una pagina di pagamento configurata nella dashboard, il terminale virtuale oppure il link di pagamento di un Gateway creato via API.

Scegli l'URL da incorporare#

<instance> è il tuo instance name; il valore tid è l'ID di una pagina di pagamento creata con il tool Pages nella dashboard.

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

Una larghezza di 530 e un'altezza di 700 pixel sono valori di partenza collaudati; con gli eventi di resize qui sotto l'altezza si adatta da sola.

Supporto wallet: l'attributo allow#

Mantieni l'attributo allow="payment *" sul frame: Google Pay funziona solo se è presente. Senza, il pulsante del wallet non compare nel modulo incorporato.

Metodi che non funzionano dentro un iFrame#

Per motivi di sicurezza alcuni metodi di pagamento rifiutano l'esecuzione embedded, tra cui PostFinance Pay, Reka Pay, PayPal e Coinbase. PostFinance viene inoltre disattivato quando il browser blocca i cookie di terze parti, comportamento predefinito su iOS e macOS.

Per mantenere disponibili questi metodi, aggiungi il parametro GET &breakIframe=true all'URL incorporato. La pagina di pagamento esterna interessata si aprirà in una nuova scheda del browser invece che nel frame.

Reagisci agli eventi della pagina di pagamento#

La pagina incorporata comunica con il tuo sito tramite postMessage. I passaggi sono due: dopo il caricamento dell'iFrame invii un handshake con la tua origin, così la pagina è autorizzata a rispondere; da quel momento la pagina invia messaggi JSON con gli eventi seguenti.

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

Non aggiungere il parametro appview all'URL incorporato se usi l'altezza dinamica: le due cose si escludono a vicenda.

Conferma il pagamento lato server#

Non esporre mai l'API Secret nel frontend e non segnare un ordine come pagato solo perché l'evento transaction riporta un successo. Conferma lo stato finale tramite i webhook con la verifica della firma, oppure recupera la transazione via API.