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.
https://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16Verwenden 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
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| instance | string | Ja | Name Ihrer Händler-Instance; identifiziert Ihr Konto bei jedem API-Aufruf. |
Body-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| amount | integer | Ja | Zahlbetrag in Minoreinheiten der Währung; CHF 89.25 wird zu 8925. |
| currency | string | Ja | Währung der Zahlung als ISO-4217-Code, zum Beispiel CHF oder EUR. |
| purpose | string | Nein | Beschreibung der Zahlung, die dem Kunden auf der Zahlungsseite angezeigt wird. |
| referenceId | string | Nein | Ihre eigene Bestellreferenz; sie wird in Responses und Webhooks zurückgegeben, damit Sie die Zahlung zuordnen können. |
| successRedirectUrl | string | Nein | URL-codierte Adresse, zu der der Kunde nach erfolgreicher Zahlung zurückkehrt. |
| failedRedirectUrl | string | Nein | URL-codierte Adresse, zu der der Kunde nach fehlgeschlagener Zahlung zurückkehrt. |
| cancelRedirectUrl | string | Nein | URL-codierte Adresse, zu der der Kunde nach manuellem Abbruch der Zahlung zurückkehrt. |
| vatRate | float | Nein | Mehrwertsteuersatz in Prozent für die Zahlung. Default: null. |
| sku | string | Nein | Artikelnummer (Stock Keeping Unit) des bezahlten Produkts. |
| basket | array of objects | Nein | Produktpositionen mit name, description, quantity, amount (Minoreinheiten) und vatRate (Prozent); die Summe aller Positionen muss amount entsprechen. |
| psp | array of integers | Nein | IDs der anzubietenden Payment Provider; ohne Angabe werden alle auf Ihrer Instance aktiven Provider angeboten. |
| pm | array of strings | Nein | Identifier der anzuzeigenden Zahlungsmethoden, um die Auswahl einzuschränken. |
| preAuthorization | boolean | Nein | Autorisiert und hinterlegt das Zahlungsmittel für eine spätere Belastung (Typ Authorization). Default: false. |
| reservation | boolean | Nein | Reserviert den Betrag für ein späteres Capture (Typ Reservation). Default: false. |
| chargeOnAuthorization | boolean | Nein | Erfordert preAuthorization auf true; belastet den Betrag bereits bei der ersten Zahlung. |
| reserveOnAuthorization | boolean | Nein | Erfordert preAuthorization auf true; erstellt aus der Autorisierung der ersten Zahlung eine Reservation. |
| fields | object | Nein | Kontaktdaten, die zusammen mit der Zahlung gespeichert werden; siehe die unterstützten Feldnamen unten. |
| language | string | Nein | Sprache der Zahlungsseite als ISO-639-1-Code, zum Beispiel de, fr, it oder en. |
| skipResultPage | boolean | Nein | Überspringt die Ergebnisseite und leitet direkt auf Ihre Success- oder Failed-URL weiter. Default: false. |
| validity | integer | Nein | Gültigkeit des Gateways in Minuten. |
| subscriptionState | boolean | Nein | Behandelt die Zahlung als Subscription. Default: false. |
| subscriptionInterval | string | Nein | Abrechnungsintervall der Subscription in Periodennotation, zum Beispiel P1M für einen Monat. |
| subscriptionPeriod | string | Nein | Gesamtdauer der Subscription in Periodennotation. |
| subscriptionCancellationInterval | string | Nein | Frist, innerhalb derer die Subscription gekündigt werden kann, in Periodennotation. |
| buttonText | array of strings | Nein | Eigene Beschriftung, die den Standardtext des Bezahlbuttons ersetzt. |
| lookAndFeelProfile | string | Nein | UUID des Look-and-Feel-Profils für die Zahlungsseite. |
| successMessage | string | Nein | Eigene Meldung, die nach erfolgreicher Zahlung auf der Ergebnisseite angezeigt wird. |
| qrCodeSessionId | string | Nein | Session-ID eines gescannten statischen QR-Codes; nur für statische TWINT-QR-Zahlungen relevant. |
| applicationFee | integer | Nein | Gebühr in Minoreinheiten der Währung, die als Application Fee einbehalten wird. |
| isPriceExclusiveVat | boolean | Nein | Wenn true, wird die Mehrwertsteuer zusätzlich zu amount berechnet statt darin enthalten zu sein. |
| concardisOrderId | string | Nein | Bestell-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_1biscustom_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
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"}
}
}'<?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.
{
"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-Status | Bedeutung | Empfohlene Massnahme |
|---|---|---|
| 400 | Die 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. |
| 404 | Zur 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.