FlowAlp

Gateway erstellen

July 30, 2026

Gateway mit der FlowAlp Pay Merchant API erstellen: POST /Gateway/ mit Parametertabelle, curl- und PHP-SDK-Beispielen, Response und Fehlern.

Ein Gateway ist eine gehostete FlowAlp-Pay-Checkout-Session für eine einzelne Zahlung. Erstellen Sie es aus Ihrem Backend, sobald ein Kunde bezahlen möchte, und leiten Sie den Kunden anschliessend auf die in der Response zurückgegebene URL der Zahlungsseite.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16

Verwenden Sie für neue Integrationen die API-Version v1.16; v1.14 und v1.15 werden weiterhin unterstützt. Authentifizieren Sie sich mit dem Header X-API-KEY und identifizieren Sie Ihr Konto über den Query-Parameter instance — siehe Authentifizierung und Request-Format. Der Body kann als application/json (empfohlen) oder application/x-www-form-urlencoded gesendet werden.

Request

Query-Parameter

ParameterTypPflichtBeschreibung
instancestringJaName Ihrer Händler-Instance; identifiziert Ihr Konto bei jedem API-Aufruf.

Body-Parameter

ParameterTypPflichtBeschreibung
amountintegerJaZahlbetrag in Minoreinheiten der Währung; CHF 89.25 wird zu 8925.
currencystringJaWährung der Zahlung als ISO-4217-Code, zum Beispiel CHF oder EUR.
purposestringNeinBeschreibung der Zahlung, die dem Kunden auf der Zahlungsseite angezeigt wird.
referenceIdstringNeinIhre eigene Bestellreferenz; sie wird in Responses und Webhooks zurückgegeben, damit Sie die Zahlung zuordnen können.
successRedirectUrlstringNeinURL-codierte Adresse, zu der der Kunde nach erfolgreicher Zahlung zurückkehrt.
failedRedirectUrlstringNeinURL-codierte Adresse, zu der der Kunde nach fehlgeschlagener Zahlung zurückkehrt.
cancelRedirectUrlstringNeinURL-codierte Adresse, zu der der Kunde nach manuellem Abbruch der Zahlung zurückkehrt.
vatRatefloatNeinMehrwertsteuersatz in Prozent für die Zahlung. Default: null.
skustringNeinArtikelnummer (Stock Keeping Unit) des bezahlten Produkts.
basketarray of objectsNeinProduktpositionen mit name, description, quantity, amount (Minoreinheiten) und vatRate (Prozent); die Summe aller Positionen muss amount entsprechen.
psparray of integersNeinIDs der anzubietenden Payment Provider; ohne Angabe werden alle auf Ihrer Instance aktiven Provider angeboten.
pmarray of stringsNeinIdentifier der anzuzeigenden Zahlungsmethoden, um die Auswahl einzuschränken.
preAuthorizationbooleanNeinAutorisiert und hinterlegt das Zahlungsmittel für eine spätere Belastung (Typ Authorization). Default: false.
reservationbooleanNeinReserviert den Betrag für ein späteres Capture (Typ Reservation). Default: false.
chargeOnAuthorizationbooleanNeinErfordert preAuthorization auf true; belastet den Betrag bereits bei der ersten Zahlung.
reserveOnAuthorizationbooleanNeinErfordert preAuthorization auf true; erstellt aus der Autorisierung der ersten Zahlung eine Reservation.
fieldsobjectNeinKontaktdaten, die zusammen mit der Zahlung gespeichert werden; siehe die unterstützten Feldnamen unten.
languagestringNeinSprache der Zahlungsseite als ISO-639-1-Code, zum Beispiel de, fr, it oder en.
skipResultPagebooleanNeinÜberspringt die Ergebnisseite und leitet direkt auf Ihre Success- oder Failed-URL weiter. Default: false.
validityintegerNeinGültigkeit des Gateways in Minuten.
subscriptionStatebooleanNeinBehandelt die Zahlung als Subscription. Default: false.
subscriptionIntervalstringNeinAbrechnungsintervall der Subscription in Periodennotation, zum Beispiel P1M für einen Monat.
subscriptionPeriodstringNeinGesamtdauer der Subscription in Periodennotation.
subscriptionCancellationIntervalstringNeinFrist, innerhalb derer die Subscription gekündigt werden kann, in Periodennotation.
buttonTextarray of stringsNeinEigene Beschriftung, die den Standardtext des Bezahlbuttons ersetzt.
lookAndFeelProfilestringNeinUUID des Look-and-Feel-Profils für die Zahlungsseite.
successMessagestringNeinEigene Meldung, die nach erfolgreicher Zahlung auf der Ergebnisseite angezeigt wird.
qrCodeSessionIdstringNeinSession-ID eines gescannten statischen QR-Codes; nur für statische TWINT-QR-Zahlungen relevant.
applicationFeeintegerNeinGebühr in Minoreinheiten der Währung, die als Application Fee einbehalten wird.
isPriceExclusiveVatbooleanNeinWenn true, wird die Mehrwertsteuer zusätzlich zu amount berechnet statt darin enthalten zu sein.
concardisOrderIdstringNeinBestell-ID, die an den Acquirer weitergegeben wird; nur verfügbar, wenn die entsprechende Option in Ihren Payment-Provider-Einstellungen aktiviert ist.

Das Objekt fields speichert Kontaktdaten zusammen mit der Zahlung. Jeder Eintrag verwendet den Feldnamen als Schlüssel und enthält einen value; die fünf Custom-Felder akzeptieren zusätzlich einen lokalisierten name. Unterstützte Feldnamen:

  • Identität: title, forename, surname, company
  • Adresse: street, postcode, place, country
  • Lieferadresse: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country
  • Kontakt und Einwilligungen: phone, email, date_of_birth, terms, privacy_policy
  • Freie Felder: custom_field_1 bis custom_field_5 (optional mit lokalisierter Beschriftung)

Wenn Sie den Body als application/x-www-form-urlencoded senden (zum Beispiel beim Signieren der Anfragen mit ApiSignature), halten Sie alle fields[...]-Parameter zusammen und in einer festen Reihenfolge.

Einige Optionen hängen von Ihrer Kontokonfiguration ab: Provider-IDs für psp, Methoden-Identifier für pm, Subscription-Einstellungen und providerspezifische Parameter wie concardisOrderId wirken nur, wenn die entsprechende Funktion auf Ihrer Instance aktiv ist. Wird ein optionaler Parameter abgelehnt, prüfen Sie die Konfiguration im Dashboard oder kontaktieren Sie den Support.

Beispiel-Request

Gateway erstellen (cURL)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 8925,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-001",
    "referenceId": "ORDER-2026-001",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel",
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Bernasconi"},
      "email": {"value": "anna.bernasconi@example.com"}
    }
  }'
Gateway erstellen (PHP-SDK)PHP
<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Gateway;

$client = new FlowAlpPay(
    getenv('FLOWALP_PAY_INSTANCE'),
    getenv('FLOWALP_PAY_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-001');
$gateway->setReferenceId('ORDER-2026-001');
$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);

// Store the id, then send the customer to the hosted payment page.
$gatewayId  = $response->getId();
$paymentUrl = $response->getLink();

Response

Ein erfolgreicher Aufruf liefert HTTP 200 mit dem unten gezeigten Envelope: status ist success, und data enthält das neue Gateway als einziges Element. Speichern Sie die id und leiten Sie Ihren Kunden anschliessend auf link weiter. Ein neu erstelltes Gateway startet immer mit dem Status waiting.

200 OKJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "status": "waiting",
      "hash": "cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "amount": 8925,
      "currency": "CHF",
      "preAuthorization": false,
      "reservation": false,
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Behandeln Sie den Redirect auf Ihre successRedirectUrl nie als Zahlungsnachweis. Bestätigen Sie jede Zahlung über Webhooks oder lesen Sie den aktuellen Status mit Gateway abrufen.

Fehler

HTTP-StatusBedeutungEmpfohlene Massnahme
400Die Anfrage hat die Validierung nicht bestanden, zum Beispiel fehlt ein Pflichtparameter oder ein Typ ist falsch.Korrigieren Sie den Request-Body und senden Sie die Anfrage erneut.
404Zur Anfrage wurde nichts gefunden, zum Beispiel weil der Instance-Name falsch ist.Prüfen Sie den Query-Parameter instance und die Endpoint-URL.

Fehler-Responses verwenden den Envelope {"status": "error", "message": "..."}; das allgemeine Fehlermodell finden Sie unter Fehler. Die API erlaubt 600 Anfragen pro 5 Minuten — siehe Rate limits.

Nächste Schritte: Betten Sie die Zahlungsseite mit dem Checkout-Embedding ein, folgen Sie dem kompletten Ablauf in Einmalzahlung akzeptieren oder vertiefen Sie die Vorautorisierung und Abos.