FlowAlp

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

Installation per Composerbash
composer require payrexx/payrexx

Das 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

Client-SetupPHP
<?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
);
PositionWertBeschreibung
1InstanznameDie Subdomain Ihrer Zahlungsseite (demo-shop bei demo-shop.pay.flowalp.com) — siehe Instanzname
2API SecretAusgestellt unter API & Plugins im Dashboard — siehe API-Zugangsdaten
3Communication HandlerBelassen Sie den Default FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER
4Plattform-Domainpay.flowalp.com — der Client leitet daraus den API-Host api.pay.flowalp.com ab
5API-VersionEmpfohlen 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

Verbindungs-Smoke-TestPHP
<?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

Gehosteten Checkout erstellenPHP
<?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

Aktuellen Status lesenPHP
<?php
use FlowAlpPay\Models\Request\Gateway;

$gateway = new Gateway();
$gateway->setId(42);

$result = $client->getOne($gateway);
$status = $result->getStatus(); // e.g. waiting, confirmed, cancelled

Der 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

SDK-Exceptions abfangenPHP
<?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 405 und dann 403 liefern — 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.
  • referenceId trä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.