FlowAlp

Erste API-Anfrage

July 30, 2026

Senden Sie Ihre erste Anfrage an die FlowAlp Pay Merchant API: Zugangsdaten mit SignatureCheck prüfen, dann ein minimales Gateway per curl oder PHP.

Diese Anleitung führt Sie zu Ihren ersten beiden Aufrufen der FlowAlp Pay Merchant API: ein SignatureCheck, der Ihre Zugangsdaten prüft, ohne etwas anzulegen, gefolgt von einem minimalen Gateway — einer gehosteten Checkout-Session für eine Zahlung. Die Beispiele verwenden curl und das PHP SDK mit API-Version v1.16.

Voraussetzungen

  • Ihr Instance-Name (zum Beispiel demo-shop).
  • Ein API Secret aus dem Dashboard — siehe API-Zugangsdaten.
  • Ein Grundverständnis der Authentifizierung — siehe Authentifizierung.
  • Eine Backend-Umgebung, die ausgehende HTTPS-Aufrufe ausführen kann.
In den Beispielen verwendete Umgebungsvariablenbash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Schritt 1: Zugangsdaten prüfen

SignatureCheck validiert das Paar aus Instance und API Secret. Der Aufruf hat keine Nebenwirkungen — ideal als erster Call und als Health Check für Deployments. Details: SignatureCheck.

GEThttps://api.pay.flowalp.com/v1.16/SignatureCheck/v1.14 · v1.15 · v1.16
Zugangsdaten mit curl prüfenbash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "x-api-key: ${FLOWALP_PAY_API_SECRET}"

Gültige Zugangsdaten liefern HTTP 200 mit einem Erfolgsstatus:

AntwortJSON
{
  "status": "success",
  "data": []
}

Ist das API Secret falsch, enthält die Antwort stattdessen einen Fehlerstatus — korrigieren Sie die Zugangsdaten, bevor Sie fortfahren.

Schritt 2: Ein minimales Gateway erstellen

Ein Gateway ist eine gehostete Checkout-Session für eine Zahlung. Beträge werden immer in kleinsten Einheiten gesendet (CHF 25.00 wird zu 2500), die Währung ist ein ISO-Code, und referenceId trägt Ihre eigene Bestellnummer.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16
Gateway mit curl erstellenbash
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": 2500,
    "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"
  }'
Gateway mit dem PHP SDK erstellenPHP
<?php
require_once 'vendor/autoload.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(2500); // CHF 25.00 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');

try {
    $response = $client->create($gateway);
    echo $response->getLink() . PHP_EOL; // send your customer here
} catch (\Exception $e) {
    error_log('Gateway creation failed: ' . $e->getMessage());
}

Mehr zum SDK: PHP SDK.

Erwartete Antwort

Antwort (gekürzt)JSON
{
  "status": "success",
  "data": [
    {
      "id": 174,
      "status": "waiting",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=<hash>",
      "amount": 2500,
      "currency": "CHF"
    }
  ]
}

Leiten Sie Ihre Kundin oder Ihren Kunden zur URL im Feld link weiter — das ist die gehostete Zahlungsseite. Das Gateway startet im Status waiting und wechselt den Status, sobald die Zahlung abgeschlossen oder abgebrochen wird. Die vollständige Parameterliste finden Sie unter Gateway erstellen.

Wenn etwas schiefgeht

HTTP-StatusWahrscheinliche UrsacheMassnahme
401 / 403Authentifizierung fehlgeschlagen oder Zugriff verweigertAPI Secret, Instance-Name und den Header x-api-key prüfen.
404Falscher Pfad oder falsche API-VersionDas Präfix /v1.16/ und den Ressourcennamen prüfen.
405, danach 403Rate Limit erreichtWarten und später erneut versuchen — siehe Rate-Limits-Anleitung.
5xxVorübergehendes serverseitiges ProblemMit begrenztem exponentiellem Backoff erneut versuchen.

Fehler-Payloads und Status-Semantik beschreiben Errors und Rate Limits.

Ein Redirect auf Ihre Success-URL ist keine Zahlungsbestätigung. Verifizieren Sie die Zahlung serverseitig über Webhooks oder durch Abrufen der Transaktion über die API (Transactions auflisten und abrufen), bevor Sie eine Bestellung ausführen.

Erste Aufrufe erfolgreich? Erkunden Sie alle Gateway-Parameter, richten Sie Webhooks ein und arbeiten Sie Testing für Entwickler durch, bevor Sie live gehen.