PHP SDK
July 30, 2026
Nutzen Sie das FlowAlp Pay PHP SDK: Installation per Composer, Client-Konfiguration, Gateways erstellen und abrufen, Fehlerbehandlung.
Das PHP SDK kapselt die FlowAlp Pay Merchant API: Es übernimmt Authentifizierung und Signaturberechnung und liefert Request-/Response-Modelle für Gateway, Transaction, Subscription und SignatureCheck — Sie bauen also nie HTTP-Anfragen von Hand.
Installation
composer require payrexx/payrexxDas Composer-Paket behält den technischen Namen der Zahlungsinfrastruktur hinter FlowAlp Pay — installieren Sie es exakt wie gezeigt. Die Beispiele unten verwenden die FlowAlp Pay Client-Benennung; weicht der Namespace Ihrer installierten SDK-Version ab, behalten Sie dasselbe Aufrufmuster bei und passen Sie nur den Namespace an.
Client konfigurieren
<?php
use FlowAlpPay\FlowAlpPay;
$client = new FlowAlpPay(
getenv('FLOWALP_TENANT'), // instance name, e.g. demo-shop
getenv('FLOWALP_API_SECRET'), // API secret from the dashboard
FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
'pay.flowalp.com', // platform domain
'1.16' // recommended API version
);| Position | Wert | Beschreibung |
|---|---|---|
| 1 | Instanzname | Die Subdomain Ihrer Zahlungsseite (demo-shop bei demo-shop.pay.flowalp.com) — siehe Instanzname |
| 2 | API Secret | Ausgestellt unter API & Plugins im Dashboard — siehe API-Zugangsdaten |
| 3 | Communication Handler | Belassen Sie den Default FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER |
| 4 | Plattform-Domain | pay.flowalp.com — der Client leitet daraus den API-Host api.pay.flowalp.com ab |
| 5 | API-Version | Empfohlen 1.16; 1.14 und 1.15 bleiben unterstützt |
Der API Secret gewährt vollen Zugriff auf Ihr Zahlungskonto. Laden Sie ihn aus einer Umgebungsvariable oder einem Secret Manager, committen Sie ihn nie und verwenden Sie das SDK nie in browserseitig sichtbarem Code.
Credentials mit SignatureCheck prüfen
<?php
use FlowAlpPay\Models\Request\SignatureCheck;
try {
$client->getOne(new SignatureCheck());
// Instance name and API secret are valid
} catch (\FlowAlpPay\FlowAlpPayException $e) {
// Wrong instance name or API secret
}Die Endpoint-Details stehen auf der SignatureCheck-Referenzseite.
Gateway erstellen
<?php
use FlowAlpPay\Models\Request\Gateway;
$gateway = new Gateway();
$gateway->setAmount(8925); // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');
$gateway->setSuccessRedirectUrl('https://merchant.example/success');
$gateway->setFailedRedirectUrl('https://merchant.example/failed');
$gateway->setCancelRedirectUrl('https://merchant.example/cancel');
$createdGateway = $client->create($gateway);
// Send the customer to the hosted payment page
$paymentPageUrl = $createdGateway->getLink();Leiten Sie auf den zurückgegebenen Zahlungslink weiter oder betten Sie ihn ein, und bestätigen Sie die Zahlung über Webhooks — der Redirect allein ist kein Beweis. Alle Create-Parameter dokumentiert Create a Gateway.
Gateway abrufen
<?php
use FlowAlpPay\Models\Request\Gateway;
$gateway = new Gateway();
$gateway->setId(42);
$result = $client->getOne($gateway);
$status = $result->getStatus(); // e.g. waiting, confirmed, cancelledDer Abruf ergänzt Webhooks, wenn Sie einen On-Demand-Statuscheck brauchen — siehe Gateway abrufen. Dasselbe create-/getOne-Muster gilt für die anderen Modelle, etwa Transaction-Operationen (auflisten und abrufen, Charge, Capture und Refund) sowie Subscriptions.
Fehler behandeln
<?php
use FlowAlpPay\FlowAlpPayException;
try {
$createdGateway = $client->create($gateway);
} catch (FlowAlpPayException $e) {
// 4xx: fix credentials, instance name or request fields - do not retry blindly
// 5xx and rate limiting: retry with exponential backoff
error_log('FlowAlp Pay error: ' . $e->getMessage());
}- Behandeln Sie
4xx-Antworten als Konfigurations-, Authentifizierungs- oder Validierungsprobleme — siehe Errors. - Behandeln Sie
5xx-Antworten als vorübergehend und wiederholen Sie mit begrenztem exponentiellem Backoff: Start bei 500 ms, pro Versuch verdoppeln, 0–300 ms Jitter, Obergrenze 30 s, maximal 5 Versuche. - Die API erlaubt 600 Anfragen pro 5 Minuten; darüber hinaus kann sie
405und dann403liefern — auch dann Backoff anwenden. Details: Rate Limits. - Loggen Sie Statuscode und bereinigte Meldung mit Ihrer Korrelationsreferenz — niemals den API Secret.
Konventionen
- Beträge sind Ganzzahlen in Minor Units: CHF 89.25 →
8925. - Währungen verwenden ISO-Codes wie
CHF,EUR,USD. referenceIdträgt Ihre Bestell-ID und kommt in den Webhook-Events zurück.
Nächster Schritt: Senden Sie Ihre erste API-Anfrage und richten Sie danach Webhooks für die zuverlässige Zahlungsbestätigung ein.