API-Versionen und Changelog

Die FlowAlp Pay Merchant API wird über den URL-Pfad versioniert. Jede Anfrage deklariert die erwartete Version: Bestehende Integrationen bleiben stabil, während Neuerungen in neueren Versionen erscheinen.

So funktioniert die Versionierung#

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

Das Versionssegment (zum Beispiel v1.16) bestimmt das API-Verhalten für genau diese Anfrage. Es gibt keinen kontoweiten Schalter: Zwei Ihrer Systeme können gleichzeitig unterschiedliche Versionen aufrufen, was schrittweise Migrationen erleichtert. Die allgemeinen URL-Konventionen finden Sie unter Request-Format.

Unterstützte Versionen#

Verwenden Sie v1.16, sofern Sie nicht eine ältere Integration betreiben, die noch nicht dagegen getestet wurde.

Version festlegen#

REST-Clients legen die Version direkt im URL-Pfad fest:

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

Der PHP-Client erhält die Version — ohne führendes v — als fünftes Konstruktor-Argument:

<?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'
);

Vorgehen beim Upgrade#

1. Lesen Sie das Changelog unten für jede Version zwischen Ihrer aktuellen und der Zielversion.
2. Ändern Sie das Versionssegment (oder das SDK-Konstruktor-Argument) zuerst in einer Staging-Umgebung.
3. Führen Sie einen Smoke-Test der Zugangsdaten mit SignatureCheck durch und testen Sie anschließend Ihre Kernabläufe End-to-End: Checkout, Webhook-Verarbeitung, Capture und Refund.
4. Vergleichen Sie die Antwortfelder, die Ihr Code auswertet — besonders dort, wo das Changelog geänderte Antwortstrukturen erwähnt.
5. Rollen Sie nach Produktion aus und überwachen Sie die Fehlerraten; bei Bedarf wechseln Sie das Versionssegment einfach zurück.

Einen strukturierten Testplan finden Sie unter Testing für Entwickler.

Changelog#

v1.16#

• Auszahlungsdetails: Wiederholte Auszahlungsversuche werden nicht mehr zu einem einzelnen aggregierten Eintrag zusammengefasst, der zuvor ein leeres Transaction-Objekt enthielt. Die Detailantwort einer Auszahlung löst solche Aggregate jetzt in die ursprünglichen, zugrunde liegenden Überweisungen auf — Sie sehen also die einzelnen Transaktionen hinter einer Auszahlung. Siehe Payouts API.

v1.15#

• Fehlerbehandlung: Fehlgeschlagene Anfragen liefern einen für den Fehler spezifischen HTTP-Statuscode statt einer generischen Antwort. Die Änderung betrifft alle Endpoints; richten Sie Ihre Fehlerbehandlung nach Merchant API Fehler aus.

v1.14#

v1.14 ist die Basis des aktuell unterstützten Bereichs. Dafür sind keine eigenen Changelog-Einträge veröffentlicht; betrachten Sie sie als Referenzverhalten, das v1.15 und v1.16 verfeinern.