Integrazione nelle app mobile

Le app native e ibride usano lo stesso checkout FlowAlp Pay ospitato del web. Il pattern poggia su due elementi: il tuo backend crea il pagamento e l'app mostra il link di pagamento in una WebView o in un browser in-app, mentre i deep link riportano poi il cliente nell'app.

Flusso consigliato#

1. Il tuo backend crea un Gateway con importo, valuta, referenceId e URL di redirect — l'API Secret non viene mai distribuito dentro l'app.
2. L'app apre il link di pagamento restituito in una WebView oppure, preferibile per wallet e 3-D Secure, nel componente browser di sistema (SFSafariViewController su iOS, Custom Tabs su Android).
3. Il cliente completa il pagamento sulla pagina ospitata.
4. Il redirect di successo, errore o annullamento riporta il cliente indietro — fai puntare questi URL a deep link di proprietà della tua app.
5. L'app chiede al tuo backend lo stato dell'ordine; il backend lo ha confermato tramite webhook o retrieve via API.

Crea il Gateway con URL di ritorno 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"
  }'

Preferisci gli Universal Link (iOS) e gli App Link (Android) agli URL scheme personalizzati: il sistema operativo li convalida sul tuo dominio e, se l'app manca, ricadono sul browser. Considera i tre URL di ritorno pura navigazione: arrivare all'URL di successo non prova il pagamento.

Ascolta gli eventi di pagamento nella WebView#

Quando la pagina di pagamento gira dentro una pagina ospitata in WebView, comunica i progressi tramite postMessage, esattamente come descritto nella guida iFrame. Invia l'handshake con la origin appena la pagina è caricata, poi osserva l'evento 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
      }
    }
  });
});

Nelle WebView in stile React Native, inietta un piccolo listener che inoltra i messaggi di window al guscio dell'app ed elaborali nel message handler dell'app. Attenzione alla differenza di piattaforma per l'handshake della origin: su Android va iniettato prima del caricamento del contenuto, su iOS va inviato a caricamento concluso.

Metodi con cambio app: TWINT e wallet#

Alcuni metodi di pagamento escono dalla tua app durante il pagamento: TWINT passa alla propria app sullo stesso dispositivo, mentre Apple Pay e Google Pay aprono i fogli del sistema operativo. Assicurati che il componente browser che usi consenta l'apertura di app esterne e torni pulitamente al checkout. Quali metodi compaiono dipende dalla configurazione del tuo account — vedi metodi di pagamento.

Conferma lato server prima di evadere#

Ritorni via deep link, eventi WebView e schermate di successo possono essere falsificati o andare persi. Evadi un ordine solo dopo che il backend ha ricevuto il webhook — con verifica della firma — o ha recuperato la transazione via API. Tratta annullamento e timeout come stati distinti, non come lo stesso tipo di errore.

Testa su dispositivi reali#

• Esegui scenari di successo, errore, annullamento e checkout abbandonato su dispositivi fisici iOS e Android.
• Verifica il giro completo dei deep link per ogni metodo di pagamento offerto, inclusi quelli con cambio app.
• Usa la modalità TEST e le carte di test prima di addebitare denaro reale.