Authentification Merchant API

La Merchant API exige une instance valide et un API Secret. Vous pouvez vous authentifier de deux façons :

• X-API-KEY (recommandé) — en-tête HTTP avec l'API Secret
• ApiSignature — HMAC-SHA256 calculé sur les paramètres de la requête

Cette section est importante si vous n'utilisez pas de SDK. Si vous développez en PHP, envisagez le PHP SDK (package technique basé sur le Payrexx PHP SDK).

TODO FlowAlp: creare e collegare sdk/php

Prérequis

• Nom de l'instance
• Identifiants API
• API Secret disponible en variable d'environnement, par exemple FLOWALP_PAY_API_SECRET

Authentification avec X-API-KEY (recommandé)

Passez l'API Secret dans l'en-tête HTTP :

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

Exemple :

# 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.

Authentification avec ApiSignature

ApiSignature est un HMAC selon la RFC 2104.

Règles de l'API Reference :

• calculez la signature sur tous les paramètres sauf instance ;
• construisez la query string URL-encodée des paramètres ;
• calculez le HMAC-SHA256 binaire avec l'API Secret comme clé ;
• encodez le résultat en Base64 ;
• envoyez la valeur dans le paramètre ApiSignature.

Algorithme (équivalent PHP de la source) :

# 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

Encodage de la query string

La query string utilisée pour la signature doit être encodée selon la RFC 1738 : les espaces deviennent +.

N'inventez pas de variantes d'algorithme. Si votre langage produit un encodage différent, comparez le résultat avec un payload de test connu.

Exemple de signature TypeScript

# 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!),
};

Format de requête

Le payload peut être :

Format | Note
JSON | Recommandé
`application/x-www-form-urlencoded` | RFC 3986 ; espaces percent-encodés en `%20` dans le payload

URL de base :

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

Champ | Emplacement | Type | Obligatoire | Description
instance | query | string | oui | Nom de l'instance marchand
object | path | string | oui | Ressource API
id | path | string | non* | Entité unique pour GET/PUT/DELETE
X-API-KEY | header | string | oui** | API Secret
ApiSignature | body/query | string | oui** | Alternative à X-API-KEY

\ obligatoire lors d'une opération sur une entité unique \\* utilisez une des deux méthodes d'authentification

Rate limit

Limite | Détail
600 requêtes / 5 minutes | Appliqué via AWS WAF

Si vous dépassez la limite, vous pouvez d'abord recevoir 405 Method Not Allowed, puis 403 Forbidden.

Pratiques recommandées :

• réessayer avec un backoff exponentiel sur les 405/403 liés au rate limiting ;
• lorsque c'est possible, agréger les opérations plutôt que de multiplier les requêtes.

Détails : Rate limits.

TODO FlowAlp: creare e collegare api/rate

Sécurité

• Préférez X-API-KEY côté backend ; ne l'utilisez pas dans les navigateurs ou applications publiques.
• Ne journalisez ni l'en-tête X-API-KEY ni ApiSignature.
• Faites tourner les identifiants compromis.
• Utilisez toujours HTTPS.

Étapes suivantes

• Format de requête
• Première requête API
• Créer un Gateway

TODO FlowAlp: creare e collegare request