FlowAlp

SDK PHP

July 30, 2026

Utilisez le SDK PHP FlowAlp Pay : installation via Composer, configuration du client, création et récupération de Gateways, gestion d'erreurs.

Le SDK PHP encapsule la Merchant API de FlowAlp Pay : il gère l'authentification et le calcul de signature et fournit des modèles de requête/réponse pour Gateway, Transaction, Subscription et SignatureCheck — vous ne construisez donc jamais de requêtes HTTP à la main.

Installation

Installation via Composerbash
composer require payrexx/payrexx

Le package Composer conserve le nom technique de l'infrastructure de paiement derrière FlowAlp Pay — installez-le exactement comme indiqué. Les exemples ci-dessous utilisent la nomenclature du client FlowAlp Pay ; si le namespace exposé par votre version du SDK diffère, gardez le même schéma d'appel et adaptez uniquement le namespace.

Configurer le client

Configuration du clientPHP
<?php
use FlowAlpPay\FlowAlpPay;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),          // instance name, e.g. demo-shop
    getenv('FLOWALP_API_SECRET'),      // API secret from the dashboard
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',                 // platform domain
    '1.16'                             // recommended API version
);
PositionValeurDescription
1Nom d'instanceLe sous-domaine de votre page de paiement (demo-shop pour demo-shop.pay.flowalp.com) — voir nom d'instance
2API SecretÉmis sous API & Plugins dans le dashboard — voir identifiants API
3Communication handlerGardez la valeur par défaut FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER
4Domaine de la plateformepay.flowalp.com — le client en dérive l'hôte API api.pay.flowalp.com
5Version d'API1.16 recommandée ; 1.14 et 1.15 restent supportées

L'API Secret donne un accès complet à votre compte de paiement. Chargez-le depuis une variable d'environnement ou un gestionnaire de secrets, ne le committez jamais et n'utilisez jamais le SDK dans du code exposé au navigateur.

Vérifier les identifiants avec SignatureCheck

Smoke test de connexionPHP
<?php
use FlowAlpPay\Models\Request\SignatureCheck;

try {
    $client->getOne(new SignatureCheck());
    // Instance name and API secret are valid
} catch (\FlowAlpPay\FlowAlpPayException $e) {
    // Wrong instance name or API secret
}

Les détails de l'endpoint figurent sur la page de référence SignatureCheck.

Créer un Gateway

Créer un checkout hébergéPHP
<?php
use FlowAlpPay\Models\Request\Gateway;

$gateway = new Gateway();
$gateway->setAmount(8925);            // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');
$gateway->setSuccessRedirectUrl('https://merchant.example/success');
$gateway->setFailedRedirectUrl('https://merchant.example/failed');
$gateway->setCancelRedirectUrl('https://merchant.example/cancel');

$createdGateway = $client->create($gateway);

// Send the customer to the hosted payment page
$paymentPageUrl = $createdGateway->getLink();

Redirigez vers le lien de paiement renvoyé ou intégrez-le, et confirmez le paiement via les webhooks — la redirection seule n'est pas une preuve. Tous les paramètres de création sont documentés dans Create a Gateway.

Récupérer un Gateway

Lire le statut courantPHP
<?php
use FlowAlpPay\Models\Request\Gateway;

$gateway = new Gateway();
$gateway->setId(42);

$result = $client->getOne($gateway);
$status = $result->getStatus(); // e.g. waiting, confirmed, cancelled

La récupération complète les webhooks quand il vous faut un contrôle de statut à la demande — voir Récupérer un Gateway. Le même schéma create / getOne s'applique aux autres modèles, par exemple les opérations Transaction (lister et récupérer, débit, capture et remboursement) et les Subscriptions.

Gérer les erreurs

Attraper les exceptions du SDKPHP
<?php
use FlowAlpPay\FlowAlpPayException;

try {
    $createdGateway = $client->create($gateway);
} catch (FlowAlpPayException $e) {
    // 4xx: fix credentials, instance name or request fields - do not retry blindly
    // 5xx and rate limiting: retry with exponential backoff
    error_log('FlowAlp Pay error: ' . $e->getMessage());
}
  • Traitez les réponses 4xx comme des problèmes de configuration, d'authentification ou de validation — voir erreurs.
  • Traitez les réponses 5xx comme transitoires et réessayez avec un backoff exponentiel plafonné : départ à 500 ms, doublement à chaque tentative, jitter de 0–300 ms, plafond à 30 s, 5 tentatives maximum.
  • L'API autorise 600 requêtes par 5 minutes ; au-delà, elle peut répondre 405 puis 403 — appliquez aussi le backoff dans ce cas. Détails : limites de débit.
  • Journalisez le code de statut et un message assaini avec votre référence de corrélation — jamais l'API Secret.

Conventions

  • Les montants sont des entiers en unités mineures : CHF 89.25 → 8925.
  • Les devises utilisent des codes ISO comme CHF, EUR, USD.
  • referenceId porte votre ID de commande et revient dans les événements webhook.

Étape suivante : lancez votre première requête API, puis branchez les webhooks pour une confirmation fiable des paiements.