Merchant API Authentifizierung

Die Merchant API erfordert eine gültige Instance und ein API Secret. Sie können sich auf zwei Arten authentifizieren:

• X-API-KEY (empfohlen) — HTTP-Header mit dem API Secret
• ApiSignature — HMAC-SHA256 berechnet über die Anfrageparameter

Dieser Abschnitt ist relevant, wenn Sie kein SDK verwenden. Wenn Sie in PHP entwickeln, erwägen Sie das PHP SDK (technisches Paket auf Basis des Payrexx PHP SDK).

TODO FlowAlp: creare e collegare sdk/php

Voraussetzungen

• Instance-Name
• API-Zugangsdaten
• API Secret als Umgebungsvariable verfügbar, beispielsweise FLOWALP_PAY_API_SECRET

Authentifizierung mit X-API-KEY (empfohlen)

Übergeben Sie das API Secret im HTTP-Header:

# http
X-API-KEY: <api-secret>

Beispiel:

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "X-API-KEY: <api-secret>"

# javascript
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)}`,
  {
    method: "GET",
    headers: {
      "X-API-KEY": apiSecret,
    },
  }
);

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

TODO FlowAlp: confirm that SignatureCheck is the official endpoint to verify credentials/signature in the current version before publication.

Authentifizierung mit ApiSignature

ApiSignature ist ein HMAC gemäß RFC 2104.

Regeln aus der API-Referenz:

• berechnen Sie die Signatur über alle Parameter außer instance;
• bauen Sie die URL-kodierte Query-String der Parameter;
• berechnen Sie das binäre HMAC-SHA256 mit dem API Secret als Schlüssel;
• kodieren Sie das Ergebnis als Base64;
• senden Sie den Wert im Parameter ApiSignature.

Algorithmus (PHP-Äquivalent aus der Quelle):

# php
base64_encode(hash_hmac('sha256', http_build_query($params, null, '&'), $apiSecret, true));

Shell:

# bash
echo -n "HTTP-QUERY-STRING" | openssl dgst -sha256 -hmac "API-SECRET" -binary | openssl enc -base64

Kodierung der Query-String

Die für die Signatur verwendete Query-String muss nach RFC 1738 kodiert sein: Leerzeichen werden zu +.

Erfinden Sie keine Algorithmus-Varianten. Wenn Ihre Sprache eine andere Kodierung erzeugt, vergleichen Sie das Ergebnis mit einem bekannten Test-payload.

TypeScript-Beispiel für die Signatur

# typescript
import qs from "qs";
import Base64 from "crypto-js/enc-base64";
import hmacSHA256 from "crypto-js/hmac-sha256";

function buildSignature(data: Record<string, unknown>, secret: string): string {
  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!),
};

Anfrageformat

Der payload kann sein:

Format | Hinweis
JSON | Empfohlen
`application/x-www-form-urlencoded` | RFC 3986; Leerzeichen im payload percent-kodiert als `%20`

Base-URL:

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

Feld | Ort | Typ | Pflicht | Beschreibung
instance | query | string | ja | Name der Händler-Instance
object | path | string | ja | API-Ressource
id | path | string | nein* | Einzelne Entität für GET/PUT/DELETE
X-API-KEY | header | string | ja** | API Secret
ApiSignature | body/query | string | ja** | Alternative zu X-API-KEY

\ erforderlich bei Operationen auf einer einzelnen Entität \\* verwenden Sie eine der beiden Authentifizierungsmethoden

Rate limit

Limit | Detail
600 Anfragen / 5 Minuten | Durchgesetzt über AWS WAF

Wenn Sie das Limit überschreiten, erhalten Sie möglicherweise zuerst 405 Method Not Allowed, danach 403 Forbidden.

Empfohlene Praktiken:

• Retry mit exponential backoff bei 405/403 im Zusammenhang mit rate limiting;
• wo möglich, Operationen aggregieren statt Anfragen zu multiplizieren.

Details: Rate limits.

TODO FlowAlp: creare e collegare api/rate

Sicherheit

• Bevorzugen Sie X-API-KEY auf dem Backend; verwenden Sie ihn nicht in Browsern oder öffentlichen Apps.
• Loggen Sie weder den Header X-API-KEY noch ApiSignature.
• Rotieren Sie kompromittierte Zugangsdaten.
• Verwenden Sie immer HTTPS.

Nächste Schritte

• Anfrageformat
• Erste API-Anfrage
• Gateway erstellen

TODO FlowAlp: creare e collegare request