Einmalzahlung akzeptieren

Die Einmalzahlung ist der Standard-Zahlungstyp bei FlowAlp Pay: Der Kunde zahlt einmal, der Betrag wird sofort belastet. Der flexibelste Weg ist das Gateway der Merchant API — Ihr Backend erstellt eine Zahlungssession, FlowAlp Pay hostet den Checkout, und ein Webhook informiert Ihr System über den Zahlungseingang. Dieser Leitfaden beschreibt den kompletten Ablauf von der Gateway-Erstellung bis zur Auslieferung der Bestellung.

Voraussetzungen#

• Ein Merchant-Konto — registrieren Sie sich auf signup.pay.flowalp.com und melden Sie sich über login.pay.flowalp.com an
• Mindestens eine aktive Zahlungsmethode — siehe Zahlungsmethoden aktivieren
• Ihr Instance-Name und Ihre API-Zugangsdaten
• Optional: das PHP SDK, wenn Ihr Backend PHP nutzt

So funktioniert der Ablauf#

1. Ihr Backend erstellt ein Gateway mit Betrag, Währung, Redirect-URLs und Ihrer Bestellreferenz.
2. Sie leiten den Kunden auf den link aus der Antwort weiter — den gehosteten Checkout auf Ihrer Zahlungsseite tenantname.pay.flowalp.com.
3. Der Kunde wählt eine Zahlungsmethode (TWINT, Karte, Wallet, …) und bezahlt.
4. FlowAlp Pay sendet einen Webhook an Ihren Server, sobald sich der Transaktionsstatus ändert.
5. Sie verifizieren die Benachrichtigung und liefern anschließend die Bestellung aus.

Gateway erstellen#

Senden Sie eine POST-Anfrage an den Gateway-Endpoint. Beträge werden immer in der kleinsten Währungseinheit angegeben (CHF 89.25 → 8925); referenceId sollte Ihre interne Bestellnummer enthalten, damit Sie die Zahlung später zuordnen können. Verwenden Sie die API-Version v1.16.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8925,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-1042",
    "referenceId": "ORDER-2026-1042",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Gateway;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$gateway = new Gateway();
$gateway->setAmount(8925); // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setPurpose('Order ORDER-2026-1042');
$gateway->setReferenceId('ORDER-2026-1042');
$gateway->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$gateway->setFailedRedirectUrl('https://shop.example.com/payment/failed');
$gateway->setCancelRedirectUrl('https://shop.example.com/payment/cancel');

$response = $client->create($gateway);
$link = $response->getLink(); // send the customer here

Die Antwort enthält die Gateway-id und einen link. Speichern Sie die ID zur Bestellung — Sie brauchen sie, um das Gateway abzurufen — und leiten Sie den Kunden auf den Link weiter. Alle Parameter (MwSt., Basket, Kontaktfelder, validity, Design-Profil, …) finden Sie unter Gateway erstellen.

Kunde zahlt im gehosteten Checkout#

Auf der gehosteten Zahlungsseite wählt der Kunde eine der auf Ihrem Konto aktivierten Zahlungsmethoden und schließt die Zahlung ab. Mit den Parametern psp und pm schränken Sie die Auswahl pro Zahlung ein — siehe Zahlungsmethoden. Danach wird der Browser auf Ihre Success-, Failed- oder Cancel-URL weitergeleitet. Sie möchten den Checkout lieber einbetten? Er funktioniert auch im iFrame oder Modal-Fenster.

Zahlung server-seitig bestätigen#

FlowAlp Pay ruft Ihren Webhook-Endpoint bei jeder Statusänderung der Transaktion auf. Eine Einmalzahlung ist erfolgreich, wenn die Transaktion den Status confirmed erreicht. Prüfen Sie die Webhook-Signatur, bevor Sie dem Payload vertrauen, oder bestätigen Sie den Status unabhängig, indem Sie das Gateway oder die Transaktion per API abrufen.

Bestellung ausliefern#

• Ordnen Sie die Benachrichtigung über referenceId (oder die gespeicherte Gateway-ID) Ihrer Bestellung zu.
• Verarbeiten Sie jede Transaktion genau einmal — Webhooks können erneut gesendet werden, gestalten Sie Ihren Handler also idempotent.
• Erst danach versenden Sie die Ware, schalten Zugänge frei oder markieren die Rechnung als bezahlt.