Première requête API

Ce guide vous mène de la configuration des identifiants à une requête HTTP authentifiée vers la Merchant API FlowAlp Pay.

Prérequis

• Nom d'instance connu (Nom de l'instance)
• API Secret créé (Identifiants API)
• Authentification comprise (Authentification)
• Environnement capable d'effectuer des appels HTTPS sortants

Variables d'environnement recommandées :

# bash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Version de l'API

Les exemples utilisent la version exposée comme URL serveur dans l'API Reference actuelle :

# text
https://api.pay.flowalp.com/v1.16/

TODO FlowAlp: align the recommended version if the merchant guide (/account/api-and-plugins) still cites 1.13.

Procédure

1. Vérifier l'instance et le secret

Vérifiez que :

• l'instance correspond au sous-domaine https://<instance>.pay.flowalp.com ;
• l'API Secret est la valeur copiée depuis API and Plugins (pas une valeur d'exemple).

2. Envoyer une requête de contrôle authentifiée

Exemple avec l'en-tête X-API-KEY :

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --fail-with-body \
  --show-error

TODO FlowAlp: verify SignatureCheck endpoint and response body on FlowAlp Pay white-label before publication. Alternatively use a documented read-only GET (e.g. payment providers list) as a smoke test.

3. Interpréter le résultat

Statut | Signification | Action recommandée
2xx | Identifiants et instance acceptés | Passer à la création d'un Gateway de test
401 / 403 | Authentification échouée ou accès refusé | Revérifier l'API Secret, l'instance et la méthode d'auth
404 | Chemin ou ressource introuvable | Vérifier la version de l'API et le chemin
405 puis 403 | Possible rate limit WAF | Attendre et réessayer avec backoff

4. Créer un Gateway de test (étape suivante typique)

Champs minimum requis par Créer un Gateway : amount (centimes) et currency.

# bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 2500,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-001",
    "referenceId": "ORDER-2026-001",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

TODO FlowAlp: verify whether the Gateway endpoint accepts application/json or requires application/x-www-form-urlencoded on FlowAlp Pay (source OpenAPI lists form-urlencoded). Adjust the example before publication.

Après création, la réponse inclut l'URL de paiement du Gateway. Redirigez le client vers cette URL (ou utilisez-la dans un embed).

Un redirect vers l'URL de succès seul ne confirme pas le paiement. Confirmez toujours via webhook et/ou récupération de la transaction/du Gateway.

Exemple Node.js

# javascript
const instanceName = process.env.FLOWALP_PAY_INSTANCE;
const apiSecret = process.env.FLOWALP_PAY_API_SECRET;

async function createGateway() {
  const url = `https://api.pay.flowalp.com/v1.16/Gateway/?instance=${encodeURIComponent(instanceName)}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-KEY": apiSecret,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 2500,
      currency: "CHF",
      purpose: "Order ORDER-2026-001",
      referenceId: "ORDER-2026-001",
      successRedirectUrl: "https://shop.example.com/payment/success",
      failedRedirectUrl: "https://shop.example.com/payment/failed",
      cancelRedirectUrl: "https://shop.example.com/payment/cancel",
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Create Gateway failed: ${response.status} ${body}`);
  }

  return response.json();
}

Sécurité

• Exécutez ces appels uniquement depuis le backend.
• N'affichez pas FLOWALP_PAY_API_SECRET dans les logs.
• Utilisez des montants de test et des URLs de redirect jusqu'à la checklist de mise en production.

TODO FlowAlp: creare e collegare testing/launch

Étapes suivantes

• Créer un Gateway — paramètres complets
• Configurer les webhooks
• Testing

TODO FlowAlp: creare e collegare le pagine successive