Erste API-Anfrage

Dieser Leitfaden führt Sie von der Einrichtung der Zugangsdaten bis zu einer authentifizierten HTTP-Anfrage an die FlowAlp Pay Merchant API.

Voraussetzungen

• Bekannter Instance-Name (Instance-Name)
• Erstelltes API Secret (API-Zugangsdaten)
• Authentifizierung verstanden (Authentifizierung)
• Umgebung, die ausgehende HTTPS-Aufrufe ausführen kann

Empfohlene Umgebungsvariablen:

# bash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

API-Version

Die Beispiele verwenden die Version, die in der aktuellen API-Referenz als Server-URL ausgewiesen ist:

# text
https://api.pay.flowalp.com/v1.16/

TODO FlowAlp: align the recommended version if the merchant guide (/account/api-and-plugins) still cites 1.13.

Vorgehen

1. Instance und Secret prüfen

Stellen Sie sicher, dass:

• die Instance dem Subdomain https://<instance>.pay.flowalp.com entspricht;
• das API Secret der aus API and Plugins kopierte Wert ist (kein Beispielwert).

2. Authentifizierte Prüfanfrage senden

Beispiel mit dem Header X-API-KEY:

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --fail-with-body \
  --show-error

TODO FlowAlp: verify SignatureCheck endpoint and response body on FlowAlp Pay white-label before publication. Alternatively use a documented read-only GET (e.g. payment providers list) as a smoke test.

3. Ergebnis interpretieren

Status | Bedeutung | Empfohlene Aktion
2xx | Zugangsdaten und Instance akzeptiert | Weiter mit dem Erstellen eines Test-Gateways
401 / 403 | Authentifizierung fehlgeschlagen oder Zugriff verweigert | API Secret, Instance und Auth-Methode erneut prüfen
404 | Pfad oder Ressource nicht gefunden | API-Version und Pfad prüfen
405 dann 403 | Möglicher WAF-rate-limit | Warten und mit Backoff erneut versuchen

4. Test-Gateway erstellen (typischer nächster Schritt)

Mindestfelder laut Gateway erstellen: amount (Cent) und currency.

# 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": 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"
  }'

TODO FlowAlp: verify whether the Gateway endpoint accepts application/json or requires application/x-www-form-urlencoded on FlowAlp Pay (source OpenAPI lists form-urlencoded). Adjust the example before publication.

Nach der Erstellung enthält die Antwort die Gateway-Zahlungs-URL. Leiten Sie den Kunden per redirect zu dieser URL weiter (oder verwenden Sie sie in einem Embed).

Ein redirect zur Erfolgs-URL allein bestätigt die Zahlung nicht. Bestätigen Sie immer per webhook und/oder Abruf der Transaktion/des Gateways.

Node.js-Beispiel

# javascript
const instanceName = process.env.FLOWALP_PAY_INSTANCE;
const apiSecret = process.env.FLOWALP_PAY_API_SECRET;

async function createGateway() {
  const url = `https://api.pay.flowalp.com/v1.16/Gateway/?instance=${encodeURIComponent(instanceName)}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-KEY": apiSecret,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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",
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Create Gateway failed: ${response.status} ${body}`);
  }

  return response.json();
}

Sicherheit

• Führen Sie diese Aufrufe nur vom Backend aus.
• Drucken Sie FLOWALP_PAY_API_SECRET nicht in Logs.
• Verwenden Sie Testbeträge und Redirect-URLs, bis die Go-Live-Checkliste abgeschlossen ist.

TODO FlowAlp: creare e collegare testing/launch

Nächste Schritte

• Gateway erstellen — vollständige Parameter
• Webhooks konfigurieren
• Testing

TODO FlowAlp: creare e collegare le pagine successive