FlowAlp

Créer un Gateway

July 30, 2026

Créez un Gateway FlowAlp Pay via POST /Gateway/ : tableau complet des paramètres, exemples curl et SDK PHP, réponse et codes d'erreur.

Un Gateway est une session de checkout hébergée FlowAlp Pay pour un paiement unique. Créez-le depuis votre backend dès qu'un client souhaite payer, puis envoyez le client vers l'URL de la page de paiement renvoyée dans la réponse.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16

Utilisez la version d'API v1.16 pour toute nouvelle intégration ; v1.14 et v1.15 restent prises en charge. Authentifiez-vous avec l'en-tête X-API-KEY et identifiez votre compte avec le paramètre de requête instance — voir Authentification et Format des requêtes. Le corps peut être envoyé en application/json (recommandé) ou application/x-www-form-urlencoded.

Requête

Paramètres de requête (query)

ParamètreTypeObligatoireDescription
instancestringOuiNom de votre instance marchande ; identifie votre compte à chaque appel API.

Paramètres du corps

ParamètreTypeObligatoireDescription
amountintegerOuiMontant du paiement en unités mineures de la devise ; CHF 89.25 devient 8925.
currencystringOuiDevise du paiement au format ISO 4217, par exemple CHF ou EUR.
purposestringNonDescription du paiement affichée au client sur la page de paiement.
referenceIdstringNonVotre propre référence de commande ; renvoyée dans les réponses et les webhooks pour associer le paiement.
successRedirectUrlstringNonAdresse (encodée en URL) vers laquelle le client revient après un paiement réussi.
failedRedirectUrlstringNonAdresse (encodée en URL) vers laquelle le client revient après un paiement échoué.
cancelRedirectUrlstringNonAdresse (encodée en URL) vers laquelle le client revient après une annulation manuelle.
vatRatefloatNonTaux de TVA en pourcentage appliqué au paiement. Défaut : null.
skustringNonRéférence article (stock keeping unit) du produit payé.
basketarray of objectsNonLignes de produits avec name, description, quantity, amount (unités mineures) et vatRate (pourcentage) ; la somme des lignes doit être égale à amount.
psparray of integersNonIDs des payment providers à proposer ; si omis, tous les providers actifs sur votre instance sont proposés.
pmarray of stringsNonIdentifiants des moyens de paiement à afficher, pour restreindre le choix proposé.
preAuthorizationbooleanNonAutorise et enregistre le moyen de paiement pour un débit ultérieur (type authorization). Défaut : false.
reservationbooleanNonRéserve le montant pour une capture ultérieure (type reservation). Défaut : false.
chargeOnAuthorizationbooleanNonNécessite preAuthorization à true ; débite le montant dès le premier paiement.
reserveOnAuthorizationbooleanNonNécessite preAuthorization à true ; crée une réservation à partir de l'autorisation du premier paiement.
fieldsobjectNonDonnées de contact enregistrées avec le paiement ; voir la liste des champs pris en charge ci-dessous.
languagestringNonLangue de la page de paiement au format ISO 639-1, par exemple de, fr, it ou en.
skipResultPagebooleanNonIgnore la page de résultat et redirige directement vers votre URL de succès ou d'échec. Défaut : false.
validityintegerNonDurée de validité du Gateway, en minutes.
subscriptionStatebooleanNonTraite le paiement comme une subscription. Défaut : false.
subscriptionIntervalstringNonIntervalle de facturation de la subscription en notation de période, par exemple P1M pour un mois.
subscriptionPeriodstringNonDurée totale de la subscription en notation de période.
subscriptionCancellationIntervalstringNonDélai pendant lequel la subscription peut être résiliée, en notation de période.
buttonTextarray of stringsNonLibellé personnalisé qui remplace le texte par défaut du bouton de paiement.
lookAndFeelProfilestringNonUUID du profil Look and Feel à appliquer à la page de paiement.
successMessagestringNonMessage personnalisé affiché sur la page de résultat après un paiement réussi.
qrCodeSessionIdstringNonID de session d'un code QR statique scanné ; utile uniquement pour les paiements TWINT par QR statique.
applicationFeeintegerNonFrais en unités mineures de la devise, retenus comme application fee.
isPriceExclusiveVatbooleanNonSi true, la TVA est ajoutée en plus d'amount au lieu d'y être incluse.
concardisOrderIdstringNonID de commande transmis à l'acquéreur ; disponible uniquement si l'option correspondante est activée dans vos réglages de payment provider.

L'objet fields enregistre des données de contact avec le paiement. Chaque entrée utilise le nom du champ comme clé et contient une value ; les cinq champs custom acceptent aussi un name localisé. Champs pris en charge :

  • Identité : title, forename, surname, company
  • Adresse : street, postcode, place, country
  • Adresse de livraison : delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country
  • Contact et consentements : phone, email, date_of_birth, terms, privacy_policy
  • Champs libres : custom_field_1 à custom_field_5 (avec libellé localisable)

Si vous envoyez le corps en application/x-www-form-urlencoded (par exemple lorsque vous signez les requêtes avec ApiSignature), gardez tous les paramètres fields[...] groupés et dans un ordre fixe.

Certaines options dépendent de la configuration de votre compte : les IDs de providers pour psp, les identifiants pour pm, les réglages de subscription et les paramètres propres à un provider comme concardisOrderId ne fonctionnent que si la fonction correspondante est active sur votre instance. Si un paramètre optionnel est refusé, vérifiez votre configuration dans le dashboard ou contactez le support.

Exemple de requête

Créer un Gateway (cURL)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": 8925,
    "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",
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Bernasconi"},
      "email": {"value": "anna.bernasconi@example.com"}
    }
  }'
Créer un Gateway (SDK PHP)PHP
<?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(8925); // CHF 89.25 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');

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

// Store the id, then send the customer to the hosted payment page.
$gatewayId  = $response->getId();
$paymentUrl = $response->getLink();

Réponse

Un appel réussi renvoie HTTP 200 avec l'enveloppe ci-dessous : status vaut success et data contient le nouveau Gateway comme unique élément. Enregistrez l'id, puis redirigez votre client vers link. Un Gateway qui vient d'être créé démarre toujours avec le statut waiting.

200 OKJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "status": "waiting",
      "hash": "cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "amount": 8925,
      "currency": "CHF",
      "preAuthorization": false,
      "reservation": false,
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Ne considérez jamais la redirection vers votre successRedirectUrl comme une preuve de paiement. Confirmez chaque paiement via les webhooks ou lisez l'état actuel avec Récupérer un Gateway.

Erreurs

Statut HTTPSignificationAction recommandée
400La requête n'a pas passé la validation, par exemple un paramètre obligatoire manque ou un type est incorrect.Corrigez le corps de la requête puis renvoyez-la.
404Rien n'a été trouvé pour la requête, par exemple parce que le nom d'instance est incorrect.Vérifiez le paramètre de requête instance et l'URL de l'endpoint.

Les réponses d'erreur utilisent l'enveloppe {"status": "error", "message": "..."} ; le modèle général est décrit dans Erreurs. L'API autorise 600 requêtes par 5 minutes — voir Limites de débit.

Étapes suivantes : intégrez la page de paiement avec le Checkout embedding, suivez le flux complet dans Accepter un paiement unique, ou approfondissez la préautorisation et les abonnements.