FlowAlp

Première requête API

July 30, 2026

Envoyez votre première requête à la Merchant API FlowAlp Pay : vérifiez vos identifiants avec SignatureCheck puis créez un Gateway minimal en curl.

Ce guide vous mène à vos deux premiers appels à la Merchant API FlowAlp Pay : un SignatureCheck qui vérifie vos identifiants sans rien créer, puis un Gateway minimal — une session de checkout hébergée pour un paiement. Les exemples utilisent curl et le SDK PHP avec la version d'API v1.16.

Prérequis

  • Votre nom d'instance (par exemple demo-shop).
  • Un API Secret créé dans le dashboard — voir Identifiants API.
  • Une idée du fonctionnement de l'authentification — voir Authentification.
  • Un environnement backend capable d'effectuer des appels HTTPS sortants.
Variables d'environnement utilisées ci-dessousbash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Étape 1 : vérifier vos identifiants

SignatureCheck valide la paire instance et API Secret. L'appel n'a aucun effet de bord : c'est le premier appel idéal et un bon health check pour vos déploiements. Détails : SignatureCheck.

GEThttps://api.pay.flowalp.com/v1.16/SignatureCheck/v1.14 · v1.15 · v1.16
Vérifier les identifiants avec curlbash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "x-api-key: ${FLOWALP_PAY_API_SECRET}"

Des identifiants valides renvoient HTTP 200 avec un statut de succès :

RéponseJSON
{
  "status": "success",
  "data": []
}

Si l'API Secret est incorrect, la réponse contient un statut d'erreur — corrigez les identifiants avant de continuer.

Étape 2 : créer un Gateway minimal

Un Gateway est une session de checkout hébergée pour un paiement. Les montants s'envoient toujours en unités mineures (CHF 25.00 devient 2500), la devise est un code ISO et referenceId transporte votre propre numéro de commande.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16
Créer un Gateway avec curlbash
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"
  }'
Créer un Gateway avec le SDK PHPPHP
<?php
require_once 'vendor/autoload.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(2500); // CHF 25.00 in minor units
$gateway->setCurrency('CHF');
$gateway->setPurpose('Order ORDER-2026-001');
$gateway->setReferenceId('ORDER-2026-001');
$gateway->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$gateway->setFailedRedirectUrl('https://shop.example.com/payment/failed');
$gateway->setCancelRedirectUrl('https://shop.example.com/payment/cancel');

try {
    $response = $client->create($gateway);
    echo $response->getLink() . PHP_EOL; // send your customer here
} catch (\Exception $e) {
    error_log('Gateway creation failed: ' . $e->getMessage());
}

Pour en savoir plus sur le SDK : SDK PHP.

Réponse attendue

Réponse (abrégée)JSON
{
  "status": "success",
  "data": [
    {
      "id": 174,
      "status": "waiting",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=<hash>",
      "amount": 2500,
      "currency": "CHF"
    }
  ]
}

Redirigez votre client vers l'URL du champ link : c'est la page de paiement hébergée. Le Gateway démarre au statut waiting et change d'état dès que le client termine ou abandonne le paiement. La liste complète des paramètres se trouve dans Créer un Gateway.

En cas de problème

Statut HTTPCause probableQue faire
401 / 403Échec d'authentification ou accès refuséRevérifiez l'API Secret, le nom d'instance et l'en-tête x-api-key.
404Chemin ou version d'API incorrectsVérifiez le préfixe /v1.16/ et le nom de la ressource.
405 puis 403Limite de débit atteintePatientez et réessayez plus tard — voir le guide des limites de débit.
5xxProblème temporaire côté serveurRéessayez avec un backoff exponentiel plafonné.

Les payloads d'erreur et la sémantique des statuts sont décrits dans Erreurs et Limites de débit.

Un redirect vers votre URL de succès n'est pas une confirmation de paiement. Avant d'exécuter une commande, vérifiez le paiement côté serveur via les webhooks ou en récupérant la transaction par l'API (Lister et récupérer les Transactions).

Premiers appels réussis ? Explorez tous les paramètres du Gateway, configurez les webhooks et suivez Tests pour développeurs avant la mise en production.