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.
https://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16Utilisez 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ètre | Type | Obligatoire | Description |
|---|---|---|---|
| instance | string | Oui | Nom de votre instance marchande ; identifie votre compte à chaque appel API. |
Paramètres du corps
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| amount | integer | Oui | Montant du paiement en unités mineures de la devise ; CHF 89.25 devient 8925. |
| currency | string | Oui | Devise du paiement au format ISO 4217, par exemple CHF ou EUR. |
| purpose | string | Non | Description du paiement affichée au client sur la page de paiement. |
| referenceId | string | Non | Votre propre référence de commande ; renvoyée dans les réponses et les webhooks pour associer le paiement. |
| successRedirectUrl | string | Non | Adresse (encodée en URL) vers laquelle le client revient après un paiement réussi. |
| failedRedirectUrl | string | Non | Adresse (encodée en URL) vers laquelle le client revient après un paiement échoué. |
| cancelRedirectUrl | string | Non | Adresse (encodée en URL) vers laquelle le client revient après une annulation manuelle. |
| vatRate | float | Non | Taux de TVA en pourcentage appliqué au paiement. Défaut : null. |
| sku | string | Non | Référence article (stock keeping unit) du produit payé. |
| basket | array of objects | Non | Lignes de produits avec name, description, quantity, amount (unités mineures) et vatRate (pourcentage) ; la somme des lignes doit être égale à amount. |
| psp | array of integers | Non | IDs des payment providers à proposer ; si omis, tous les providers actifs sur votre instance sont proposés. |
| pm | array of strings | Non | Identifiants des moyens de paiement à afficher, pour restreindre le choix proposé. |
| preAuthorization | boolean | Non | Autorise et enregistre le moyen de paiement pour un débit ultérieur (type authorization). Défaut : false. |
| reservation | boolean | Non | Réserve le montant pour une capture ultérieure (type reservation). Défaut : false. |
| chargeOnAuthorization | boolean | Non | Nécessite preAuthorization à true ; débite le montant dès le premier paiement. |
| reserveOnAuthorization | boolean | Non | Nécessite preAuthorization à true ; crée une réservation à partir de l'autorisation du premier paiement. |
| fields | object | Non | Données de contact enregistrées avec le paiement ; voir la liste des champs pris en charge ci-dessous. |
| language | string | Non | Langue de la page de paiement au format ISO 639-1, par exemple de, fr, it ou en. |
| skipResultPage | boolean | Non | Ignore la page de résultat et redirige directement vers votre URL de succès ou d'échec. Défaut : false. |
| validity | integer | Non | Durée de validité du Gateway, en minutes. |
| subscriptionState | boolean | Non | Traite le paiement comme une subscription. Défaut : false. |
| subscriptionInterval | string | Non | Intervalle de facturation de la subscription en notation de période, par exemple P1M pour un mois. |
| subscriptionPeriod | string | Non | Durée totale de la subscription en notation de période. |
| subscriptionCancellationInterval | string | Non | Délai pendant lequel la subscription peut être résiliée, en notation de période. |
| buttonText | array of strings | Non | Libellé personnalisé qui remplace le texte par défaut du bouton de paiement. |
| lookAndFeelProfile | string | Non | UUID du profil Look and Feel à appliquer à la page de paiement. |
| successMessage | string | Non | Message personnalisé affiché sur la page de résultat après un paiement réussi. |
| qrCodeSessionId | string | Non | ID de session d'un code QR statique scanné ; utile uniquement pour les paiements TWINT par QR statique. |
| applicationFee | integer | Non | Frais en unités mineures de la devise, retenus comme application fee. |
| isPriceExclusiveVat | boolean | Non | Si true, la TVA est ajoutée en plus d'amount au lieu d'y être incluse. |
| concardisOrderId | string | Non | ID 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
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"}
}
}'<?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.
{
"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 HTTP | Signification | Action recommandée |
|---|---|---|
| 400 | La 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. |
| 404 | Rien 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.