FlowAlp

Request-Format

July 30, 2026

Request-Format der FlowAlp Pay Merchant API: URL-Struktur, JSON- und Form-Urlencoded-Bodies, HTTP-Verben und Beträge in Minor Units.

Alle Merchant-API-Anfragen folgen derselben URL-Struktur und denselben Konventionen. Diese Seite beschreibt, wie Sie eine Ressource adressieren, welche Content-Types unterstützt werden und welche Felder in fast jedem Aufruf vorkommen.

URL-Struktur

URL-Mustertext
https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>
ElementOrtPflichtBeschreibung
<version>pathjaAPI-Version, zum Beispiel v1.16 (empfohlen)
<Object>pathjaRessourcenname, zum Beispiel Gateway, Transaction, SignatureCheck
<id>pathnein*Entitäts-ID für GET/PUT/DELETE auf einem einzelnen Datensatz
instancequeryjaName Ihrer Händler-Instance

* Erforderlich, wenn der Aufruf eine einzelne Entität betrifft. Der Parameter instance bleibt immer in der Query-String — bei POST-Anfragen gehören alle übrigen Parameter in den Body. Siehe Instance-Name und API-Versionen und Changelog.

HTTP-Verben

OperationVerbBeispiel
ErstellenPOSTPOST /v1.16/Gateway/
Abrufen (einzeln oder Liste)GETGET /v1.16/Transaction/42/
AktualisierenPUTPUT /v1.16/Subscription/42/
Löschen / stornierenDELETEDELETE /v1.16/Gateway/42/

Content-Types

Content-TypeHinweise
application/jsonEmpfohlen
application/x-www-form-urlencodedUnterstützt; Werte percent-kodiert, Leerzeichen als %20 (RFC 3986)

Setzen Sie den Content-Type-Header passend zum gesendeten Body. Wenn Sie sich mit ApiSignature authentifizieren, beachten Sie die separate Signatur-Kodierung in Merchant API Authentifizierung.

Konventionen und häufige Felder

FeldTypBeschreibung
instancestringHändler-Kennung; immer in der Query-String
amountintegerBetrag in Minor Units: CHF 89.25 → 8925
currencystringISO-Währungscode, zum Beispiel CHF, EUR
referenceIdstringIhre eigene Bestell- oder Korrelations-ID
purposestringLesbarer Zahlungszweck

Beträge sind immer Ganzzahlen in der kleinsten Währungseinheit. Dezimalwerte wie 89.25 sind eine häufige Ursache für 400-Fehler.

Beispiele

JSON-Anfrage (empfohlen)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 8925,
    "currency": "CHF",
    "referenceId": "ORDER-975382",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'
Form-urlencoded-Anfragebash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=8925" \
  --data-urlencode "currency=CHF" \
  --data-urlencode "referenceId=ORDER-975382"
PHP SDKPHP
<?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(8925); // CHF 89.25
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');

$response = $client->create($gateway);
Typische AntwortstrukturJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "referenceId": "ORDER-975382"
    }
  ]
}

Erfolgreiche Antworten enthalten ein status-Feld und ein data-Array mit der Ressourcendarstellung; die genauen Felder hängen von der Ressource ab. Fehlgeschlagene Anfragen beschreibt Merchant API Fehler.

Häufige Fehler

  • instance im Body statt in der Query-String.
  • Fehlender Content-Type-Header oder einer, der nicht zum Body passt.
  • Beträge als Dezimalzahlen statt als Ganzzahlen in Minor Units.
  • Eine Query-String-Kodierung, die von der für ApiSignature signierten abweicht.
  • Gemischte API-Versionen in einem Ablauf ohne erneutes Testen.

Weiter geht es: Gateway erstellen — oder vertiefen Sie Fehler und Rate Limits.