Aperçu Merchant API

La Merchant API de FlowAlp Pay est une interface REST qui vous permet d'accepter et de gérer des paiements depuis votre propre backend. Vous pouvez créer des checkouts hébergés (Gateway), suivre les transactions, gérer les subscriptions, émettre des paylinks et des invoices et réconcilier les versements.

URL de base et versions#

Chaque requête cible une URL de base versionnée. La version de l'API fait partie du chemin : chaque intégration déclare ainsi explicitement le comportement sur lequel elle s'appuie :

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

Le paramètre de requête instance identifie votre compte marchand et est obligatoire à chaque appel — voir Nom d'instance. Les versions v1.14, v1.15 et v1.16 sont prises en charge ; utilisez v1.16 pour toute nouvelle intégration et consultez Versions de l'API et changelog pour les différences et les conseils de mise à niveau.

Authentification#

Les requêtes s'authentifient avec l'API Secret de votre instance. Deux méthodes sont disponibles :

• En-tête x-api-key (recommandé) : vous envoyez l'API Secret comme en-tête HTTP.
• Paramètre ApiSignature : une signature HMAC-SHA256 calculée sur les paramètres de la requête.

Consultez Authentification Merchant API pour la configuration et les exemples de code. Pour vérifier que vos identifiants fonctionnent, appelez l'endpoint SignatureCheck :

curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "x-api-key: <api-secret>"

Format des requêtes et conventions#

• application/json est recommandé ; application/x-www-form-urlencoded est également pris en charge.
• Les montants sont des entiers en unités mineures : CHF 89.25 s'envoie comme 8925.
• Les devises utilisent les codes ISO, par exemple CHF ou EUR.
• referenceId transporte votre propre identifiant de commande ou de corrélation.
• Les verbes HTTP suivent la sémantique REST : POST crée, GET récupère, PUT met à jour, DELETE supprime.

Détails et exemples : Format des requêtes.

Ressources principales#

Pages de référence : Créer un Gateway, Lister et récupérer les Transactions, API Subscriptions, API Versements, Fournisseurs et identifiants des moyens de paiement, Créer un Paylink.

Selon la configuration de votre compte, le checkout peut proposer TWINT, Visa, Mastercard, American Express, PostFinance, Apple Pay, Google Pay, PayPal, Klarna et le virement bancaire.

Erreurs et limites de débit#

• Les requêtes en échec renvoient des codes de statut HTTP explicites et un corps d'erreur JSON : Erreurs Merchant API.
• L'API autorise 600 requêtes par 5 minutes ; prévoyez des retries avec backoff : Limites de débit Merchant API.

SDK PHP#

Pour les backends PHP, le client PHP de FlowAlp Pay prend en charge l'authentification, la signature et le transport :

<?php
use FlowAlpPay\FlowAlpPay;

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

Guide complet : SDK PHP.