Mobile-App-Integration

Native und hybride Apps nutzen denselben gehosteten FlowAlp Pay Checkout wie das Web. Das Muster beruht auf zwei Bausteinen: Ihr Backend erstellt die Zahlung, die App zeigt den Zahlungslink in einer WebView oder einem In-App-Browser an — und Deep Links bringen die Kundschaft anschliessend zurück in die App.

Empfohlener Ablauf#

1. Ihr Backend erstellt ein Gateway mit Betrag, Währung, referenceId und Redirect-URLs — der API Secret wird nie mit der App ausgeliefert.
2. Die App öffnet den zurückgegebenen Zahlungslink in einer WebView oder, für Wallets und 3-D Secure bevorzugt, in der System-Browser-Komponente (SFSafariViewController auf iOS, Custom Tabs auf Android).
3. Die Kundin oder der Kunde schliesst die Zahlung auf der gehosteten Seite ab.
4. Der Success-, Failed- oder Cancel-Redirect führt zurück — richten Sie diese URLs auf Deep Links, die Ihrer App gehören.
5. Die App fragt Ihr Backend nach dem Bestellstatus; das Backend hat ihn per Webhook oder API-Abruf bestätigt.

Gateway mit Deep-Link-Rückkehr-URLs erstellen#

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"
  }'

Bevorzugen Sie Universal Links (iOS) und App Links (Android) gegenüber eigenen URL-Schemes: Das Betriebssystem validiert sie gegen Ihre Domain, und fehlt die App, greift der Browser als Fallback. Behandeln Sie alle drei Rückkehr-URLs als reine Navigation — das Erreichen der Success-URL beweist keine Zahlung.

Zahlungs-Events in der WebView abhören#

Läuft die Zahlungsseite innerhalb einer WebView-gehosteten Seite, meldet sie den Fortschritt per postMessage — genau wie im iFrame-Guide beschrieben. Senden Sie nach dem Laden den Origin-Handshake und warten Sie dann auf das transaction-Event.

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

In React-Native-artigen WebViews injizieren Sie einen kleinen Listener, der window-Messages an die App weiterreicht, und verarbeiten sie im Message-Handler der App. Beachten Sie den Plattformunterschied beim Origin-Handshake: auf Android vor dem Laden des Inhalts injizieren, auf iOS nach Abschluss des Ladens senden.

App-Switch-Methoden: TWINT und Wallets#

Einige Zahlungsmethoden verlassen Ihre App während der Zahlung: TWINT übergibt an die eigene App auf demselben Gerät, Apple Pay und Google Pay öffnen Sheets des Betriebssystems. Stellen Sie sicher, dass Ihre Browser-Komponente externe Apps öffnen darf und sauber zum Checkout zurückkehrt. Welche Methoden erscheinen, hängt von Ihrer Kontokonfiguration ab — siehe Zahlungsmethoden.

Vor der Erfüllung serverseitig bestätigen#

Deep-Link-Rückkehr, WebView-Events und Erfolgsbildschirme können gefälscht werden oder verloren gehen. Erfüllen Sie eine Bestellung erst, wenn Ihr Backend den Webhook — mit Signaturprüfung — erhalten oder die Transaktion per API abgerufen hat. Behandeln Sie Abbruch und Timeout als getrennte Zustände.

Auf echten Geräten testen#

• Testen Sie Erfolgs-, Fehler-, Abbruch- und Abandoned-Checkout-Szenarien auf physischen iOS- und Android-Geräten.
• Prüfen Sie den Deep-Link-Rundweg für jede angebotene Zahlungsmethode, inklusive App-Switch-Methoden.
• Nutzen Sie TEST-Modus und Testkarten, bevor echtes Geld fliesst.