FlowAlp

Format des requêtes

July 30, 2026

Format des requêtes de la Merchant API FlowAlp Pay : structure d'URL, corps JSON et form-urlencoded, verbes HTTP, montants en unités mineures.

Toutes les requêtes Merchant API partagent la même structure d'URL et les mêmes conventions. Cette page décrit comment adresser une ressource, quels content types sont pris en charge et quels champs apparaissent dans presque tous les appels.

Structure des URL

Modèle d'URLtext
https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>
ÉlémentEmplacementObligatoireDescription
<version>pathouiVersion de l'API, par exemple v1.16 (recommandée)
<Object>pathouiNom de la ressource, par exemple Gateway, Transaction, SignatureCheck
<id>pathnon*ID de l'entité pour GET/PUT/DELETE sur un enregistrement unique
instancequeryouiNom d'instance de votre compte marchand

* Obligatoire lorsque l'appel concerne une entité unique. Le paramètre instance reste toujours dans la query string — pour les requêtes POST, tous les autres paramètres vont dans le corps. Voir Nom d'instance et Versions de l'API et changelog.

Verbes HTTP

OpérationVerbeExemple
CréerPOSTPOST /v1.16/Gateway/
Récupérer (unique ou liste)GETGET /v1.16/Transaction/42/
Mettre à jourPUTPUT /v1.16/Subscription/42/
Supprimer / annulerDELETEDELETE /v1.16/Gateway/42/

Content types

Content-TypeRemarques
application/jsonRecommandé
application/x-www-form-urlencodedPris en charge ; valeurs percent-encodées, espaces en %20 (RFC 3986)

Définissez l'en-tête Content-Type en cohérence avec le corps envoyé. Si vous vous authentifiez avec ApiSignature, tenez compte de l'encodage de signature distinct décrit dans Authentification Merchant API.

Conventions et champs courants

ChampTypeDescription
instancestringIdentifiant du marchand ; toujours dans la query string
amountintegerMontant en unités mineures : CHF 89.25 → 8925
currencystringCode devise ISO, par exemple CHF, EUR
referenceIdstringVotre propre identifiant de commande ou de corrélation
purposestringMotif de paiement lisible

Les montants sont toujours des entiers dans la plus petite unité de la devise. Envoyer des décimales comme 89.25 est une cause fréquente d'erreurs 400.

Exemples

Requête JSON (recommandée)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 8925,
    "currency": "CHF",
    "referenceId": "ORDER-975382",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'
Requête form-urlencodedbash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=8925" \
  --data-urlencode "currency=CHF" \
  --data-urlencode "referenceId=ORDER-975382"
SDK PHPPHP
<?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
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');

$response = $client->create($gateway);
Enveloppe de réponse typeJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "referenceId": "ORDER-975382"
    }
  ]
}

Les réponses réussies contiennent un champ status et un tableau data avec la représentation de la ressource ; les champs exacts dépendent de la ressource. Les requêtes en échec sont décrites dans Erreurs Merchant API.

Erreurs de format courantes

  • instance placé dans le corps au lieu de la query string.
  • En-tête Content-Type manquant ou incohérent avec le corps.
  • Montants envoyés en décimales au lieu d'entiers en unités mineures.
  • Un encodage de query string différent de celui utilisé pour calculer ApiSignature.
  • Des versions d'API mélangées dans un même flux sans retest.

Étape suivante : créez un Gateway ou passez en revue les erreurs et les limites de débit.