FlowAlp

Merchant API Authentifizierung

July 30, 2026

Authentifizieren Sie FlowAlp Pay Merchant-API-Anfragen mit dem x-api-key-Header oder der ApiSignature-HMAC-SHA256-Signatur, mit Beispielen.

Jede Merchant-API-Anfrage muss nachweisen, dass sie von Ihrem Backend stammt. Sie benötigen Ihren Instance-Namen, das zugehörige API Secret und eine von zwei Authentifizierungsmethoden:

  • `x-api-key`-Header (empfohlen): Sie senden das API Secret mit jeder Anfrage.
  • `ApiSignature`-Parameter: Sie senden eine aus den Request-Parametern berechnete HMAC-SHA256-Signatur — das Secret selbst wird nie übertragen.

Wenn Sie mit PHP arbeiten, übernimmt das PHP SDK die Authentifizierung für Sie; diese Seite ist vor allem für direkte HTTP-Integrationen relevant.

Voraussetzungen

Option 1: x-api-key-Header (empfohlen)

Senden Sie das API Secret im HTTP-Header x-api-key. Header-Namen sind case-insensitive, X-API-KEY ist also gleichwertig:

HeaderHTTP
x-api-key: <api-secret>
Header mit SignatureCheck testenbash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "x-api-key: <api-secret>"
Reines PHP (cURL) mit x-api-keyPHP
<?php
$instance  = getenv('FLOWALP_PAY_INSTANCE');
$apiSecret = getenv('FLOWALP_PAY_API_SECRET');

$ch = curl_init(
    'https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=' . urlencode($instance)
);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-key: ' . $apiSecret]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException('FlowAlp Pay auth check failed: ' . $status);
}
Node.js mit x-api-keyJavaScript
const instanceName = process.env.FLOWALP_PAY_INSTANCE;
const apiSecret = process.env.FLOWALP_PAY_API_SECRET;

const response = await fetch(
  `https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${encodeURIComponent(instanceName)}`,
  { headers: { "x-api-key": apiSecret } }
);

if (!response.ok) {
  throw new Error(`FlowAlp Pay auth check failed: ${response.status}`);
}

Option 2: ApiSignature (HMAC-SHA256)

Im Signaturmodus übertragen Sie das Secret nicht. Stattdessen signieren Sie die Request-Parameter und senden das Ergebnis im Parameter ApiSignature. Die Signatur ist ein HMAC (RFC 2104) und entsteht so:

  1. Sammeln Sie alle Request-Parameter außer instance.
  2. Bauen Sie daraus die URL-kodierte Query-String, zum Beispiel amount=2500&currency=CHF.
  3. Berechnen Sie das binäre HMAC-SHA256 dieser Zeichenkette mit dem API Secret als Schlüssel.
  4. Kodieren Sie das Ergebnis mit Base64.
  5. Senden Sie den Wert als Parameter ApiSignature zusammen mit den übrigen Parametern.
Kanonischer Algorithmus (PHP-Einzeiler)PHP
$apiSignature = base64_encode(
    hash_hmac('sha256', http_build_query($params, '', '&'), $apiSecret, true)
);
Vollständiges PHP-Beispiel: signierte Gateway-AnfragePHP
<?php
$instance  = getenv('FLOWALP_PAY_INSTANCE');
$apiSecret = getenv('FLOWALP_PAY_API_SECRET');

$params = [
    'amount'      => 8925, // CHF 89.25 in minor units
    'currency'    => 'CHF',
    'referenceId' => 'ORDER-975382',
];

// Sign exactly the query string you send as the body.
$body = http_build_query($params, '', '&');
$params['ApiSignature'] = base64_encode(
    hash_hmac('sha256', $body, $apiSecret, true)
);

$ch = curl_init(
    'https://api.pay.flowalp.com/v1.16/Gateway/?instance=' . urlencode($instance)
);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params, '', '&'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
Bash (openssl)bash
API_SECRET="<api-secret>"
QUERY_STRING="amount=2500&currency=CHF"

SIGNATURE=$(printf '%s' "$QUERY_STRING" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary \
  | openssl enc -base64)

curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "$QUERY_STRING" \
  --data-urlencode "ApiSignature=$SIGNATURE"

Kodierung der Query-String

Die zu signierende Zeichenkette muss nach RFC 1738 form-kodiert sein — Leerzeichen werden zu +. Die Ausgabe von PHPs http_build_query() ist die Referenzimplementierung. Andere Sprachen müssen sie exakt nachbilden; achten Sie auf Zeichen wie !'()*~, die manche Bibliotheken anders kodieren (siehe den JavaScript-Helper unten). Der form-urlencoded Request-Body selbst verwendet Percent-Encoding, Leerzeichen also als %20.

Entwerfen Sie keine eigene Variante des Algorithmus. Erzeugt Ihre Bibliothek eine andere Kodierung, stimmt die Signatur nicht überein. Validieren Sie Ihre Implementierung mit dem SignatureCheck-Endpoint, bevor Sie live gehen.

JavaScript-Signatur-Helper (crypto-js)JavaScript
const qs = require("qs");
const Base64 = require("crypto-js/enc-base64");
const hmacSHA256 = require("crypto-js/hmac-sha256");

function buildSignature(data, secret) {
  let queryStr = "";
  if (data) {
    queryStr = qs.stringify(data, { format: "RFC1738" });
    queryStr = queryStr.replace(
      /[!'()*~]/g,
      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
    );
  }
  return Base64.stringify(hmacSHA256(queryStr, secret));
}

const params = { amount: 2500, currency: "CHF" };
const signed = {
  ...params,
  ApiSignature: buildSignature(params, process.env.FLOWALP_PAY_API_SECRET),
};

Welche Methode passt zu Ihnen?

Kriteriumx-api-keyApiSignature
ImplementierungsaufwandMinimal — ein HeaderErfordert exakte Query-String-Kodierung
Secret bei der ÜbertragungWird mit jeder Anfrage gesendet (immer über HTTPS)Wird nie übertragen; nur der HMAC reist mit
Typischer EinsatzServer-zu-Server-IntegrationenUmgebungen mit strengen Vorgaben zum Umgang mit Secrets

Einrichtung überprüfen

Rufen Sie nach der Konfiguration SignatureCheck auf; der Endpoint validiert Instance, Secret und — im Signaturmodus — auch Ihre Kodierung. Details: SignatureCheck: API-Zugangsdaten prüfen.

Typische ErfolgsantwortJSON
{
  "status": "success",
  "data": [
    {
      "id": 1
    }
  ]
}

Sicherheitsempfehlungen

  • Bewahren Sie das API Secret im Backend auf; betten Sie es nie in Browser, Mobile-Apps oder anderen Client-Code ein.
  • Hinterlegen Sie Secrets in Umgebungsvariablen oder einem Secret-Manager, nicht im Repository.
  • Protokollieren Sie weder den x-api-key-Header noch ApiSignature-Werte.
  • Rotieren Sie das Secret sofort, wenn Sie eine Kompromittierung vermuten.
  • Rufen Sie die API ausschließlich über HTTPS auf.

Authentifizierung eingerichtet? Fahren Sie mit dem Request-Format fort und senden Sie Ihre erste API-Anfrage.