Merchant API Überblick

Die FlowAlp Pay Merchant API ist eine REST-Schnittstelle, mit der Sie Zahlungen aus Ihrem eigenen Backend heraus annehmen und verwalten. Sie können gehostete Checkouts (Gateway) erstellen, Transaktionen nachverfolgen, Subscriptions verwalten, Paylinks und Invoices ausstellen und Auszahlungen abstimmen.

Basis-URL und Versionierung#

Jede Anfrage richtet sich an eine versionierte Basis-URL. Die API-Version ist Teil des Pfads; jede Integration legt damit explizit fest, auf welches Verhalten sie sich verlässt:

https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>

Der Query-Parameter instance identifiziert Ihr Händlerkonto und ist bei jedem Aufruf erforderlich — siehe Instance-Name. Unterstützt werden v1.14, v1.15 und v1.16; verwenden Sie für neue Integrationen v1.16 und lesen Sie API-Versionen und Changelog zu Unterschieden und Upgrades.

Authentifizierung#

Anfragen werden mit dem API Secret Ihrer Instance authentifiziert. Zwei Methoden stehen zur Verfügung:

• x-api-key-Header (empfohlen): Sie senden das API Secret als HTTP-Header.
• ApiSignature-Parameter: eine über die Request-Parameter berechnete HMAC-SHA256-Signatur.

Siehe Merchant API Authentifizierung für Einrichtung und Codebeispiele. Ob Ihre Zugangsdaten funktionieren, prüfen Sie mit dem SignatureCheck-Endpoint:

curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "x-api-key: <api-secret>"

Request-Format und Konventionen#

• application/json wird empfohlen; application/x-www-form-urlencoded wird ebenfalls unterstützt.
• Beträge sind Ganzzahlen in der kleinsten Währungseinheit: CHF 89.25 senden Sie als 8925.
• Währungen verwenden ISO-Codes wie CHF oder EUR.
• referenceId transportiert Ihre eigene Bestell- oder Korrelations-ID.
• HTTP-Verben folgen der REST-Semantik: POST erstellt, GET ruft ab, PUT aktualisiert, DELETE löscht.

Details und Beispiele: Request-Format.

Wichtigste Ressourcen#

Referenzseiten: Gateway erstellen, Transactions auflisten und abrufen, Subscriptions API, Payouts API, Zahlungsanbieter und Methoden-IDs, Paylink erstellen.

Je nach Kontokonfiguration bietet der Checkout TWINT, Visa, Mastercard, American Express, PostFinance, Apple Pay, Google Pay, PayPal, Klarna und Banküberweisung an.

Fehler und Rate Limits#

• Fehlgeschlagene Anfragen liefern aussagekräftige HTTP-Statuscodes und einen JSON-Fehlerbody: Merchant API Fehler.
• Es gelten 600 Anfragen pro 5 Minuten; planen Sie Retries mit Backoff: Merchant API Rate Limits.

PHP SDK#

Für PHP-Backends übernimmt der FlowAlp Pay PHP-Client Authentifizierung, Signierung und Transport:

<?php
use FlowAlpPay\FlowAlpPay;

$client = new FlowAlpPay(
    getenv('FLOWALP_PAY_INSTANCE'),
    getenv('FLOWALP_PAY_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

Vollständige Anleitung: PHP SDK.