Accepter un paiement unique

Le paiement unique est le type de paiement par défaut sur FlowAlp Pay : le client paie une seule fois et le montant est débité immédiatement. Le moyen le plus flexible de l'accepter est le Gateway de l'API Merchant — votre backend crée une session de paiement, FlowAlp Pay héberge le checkout et un webhook informe votre système dès que l'encaissement a eu lieu. Ce guide couvre le flux complet, de la création du Gateway à la livraison de la commande.

Prérequis#

• Un compte marchand — inscrivez-vous sur signup.pay.flowalp.com et connectez-vous via login.pay.flowalp.com
• Au moins un moyen de paiement actif — voir Activer les moyens de paiement
• Votre nom d'instance et vos identifiants API
• Optionnel : le SDK PHP si votre backend tourne en PHP

Comment fonctionne le flux#

1. Votre backend crée un Gateway avec le montant, la devise, les URL de redirect et votre référence de commande.
2. Vous redirigez le client vers le link renvoyé dans la réponse — le checkout hébergé sur votre page de paiement tenantname.pay.flowalp.com.
3. Le client choisit un moyen de paiement (TWINT, carte, wallet, …) et paie.
4. FlowAlp Pay envoie un webhook à votre serveur dès que le statut de la transaction change.
5. Vous vérifiez la notification, puis livrez la commande.

Créer le Gateway#

Envoyez une requête POST à l'endpoint Gateway. Les montants sont toujours exprimés dans la plus petite unité de la devise (CHF 89.25 → 8925) et referenceId doit contenir l'identifiant interne de votre commande afin de rapprocher le paiement ensuite. Utilisez la version d'API v1.16.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8925,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-1042",
    "referenceId": "ORDER-2026-1042",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Gateway;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$gateway = new Gateway();
$gateway->setAmount(8925); // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setPurpose('Order ORDER-2026-1042');
$gateway->setReferenceId('ORDER-2026-1042');
$gateway->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$gateway->setFailedRedirectUrl('https://shop.example.com/payment/failed');
$gateway->setCancelRedirectUrl('https://shop.example.com/payment/cancel');

$response = $client->create($gateway);
$link = $response->getLink(); // send the customer here

La réponse contient l'id du Gateway et un link. Enregistrez l'ID avec votre commande — il vous servira à récupérer le Gateway — puis redirigez le client vers le lien. Tous les paramètres (TVA, basket, champs de contact, validity, profil graphique, …) sont documentés dans Créer un Gateway.

Le client paie sur le checkout hébergé#

Sur la page de paiement hébergée, le client choisit l'un des moyens de paiement activés sur votre compte et termine le paiement. Vous pouvez restreindre le choix pour un paiement donné avec les paramètres psp et pm — voir Moyens de paiement. Le navigateur est ensuite redirigé vers votre URL de succès, d'échec ou d'annulation. Vous préférez intégrer le checkout ? Il fonctionne aussi en iFrame ou fenêtre modale.

Confirmer le paiement côté serveur#

FlowAlp Pay appelle votre endpoint webhook à chaque changement de statut de la transaction. Un paiement unique est réussi lorsque la transaction atteint le statut confirmed. Vérifiez la signature du webhook avant de faire confiance au payload, ou confirmez le statut de manière indépendante en récupérant le Gateway ou la transaction via l'API.

Livrer la commande#

• Associez la notification à votre commande via referenceId (ou l'ID du Gateway enregistré).
• Traitez chaque transaction une seule fois — les webhooks peuvent être renvoyés, rendez donc votre handler idempotent.
• Ce n'est qu'ensuite que vous expédiez la marchandise, activez l'accès ou marquez la facture comme payée.