FlowAlp

Formato delle request

July 30, 2026

Formato delle request della Merchant API FlowAlp Pay: struttura degli URL, body JSON e form-urlencoded, verbi HTTP e importi in unità minime.

Tutte le request alla Merchant API condividono la stessa struttura degli URL e le stesse convenzioni. Questa pagina descrive come indirizzare una risorsa, quali content type sono supportati e quali campi compaiono in quasi tutte le chiamate.

Struttura degli URL

Pattern dell'URLtext
https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>
ElementoPosizioneObbligatorioDescrizione
<version>pathsìVersione API, ad esempio v1.16 (consigliata)
<Object>pathsìNome della risorsa, ad esempio Gateway, Transaction, SignatureCheck
<id>pathno*ID dell'entità per GET/PUT/DELETE su un singolo record
instancequerysìInstance name del tuo account merchant

* Obbligatorio quando la chiamata riguarda una singola entità. Il parametro instance resta sempre nella query string — per le request POST tutti gli altri parametri vanno nel body. Vedi Instance name e Versioni API e changelog.

Verbi HTTP

OperazioneVerboEsempio
CreazionePOSTPOST /v1.16/Gateway/
Lettura (singola o lista)GETGET /v1.16/Transaction/42/
AggiornamentoPUTPUT /v1.16/Subscription/42/
Eliminazione / annullamentoDELETEDELETE /v1.16/Gateway/42/

Content type

Content-TypeNote
application/jsonConsigliato
application/x-www-form-urlencodedSupportato; valori percent-encoded, spazi come %20 (RFC 3986)

Imposta l'header Content-Type coerente con il body che invii. Se ti autentichi con ApiSignature, tieni presente l'encoding di firma separato descritto in Autenticazione della Merchant API.

Convenzioni e campi comuni

CampoTipoDescrizione
instancestringIdentificativo del merchant; sempre nella query string
amountintegerImporto in unità minime: CHF 89.25 → 8925
currencystringCodice valuta ISO, ad esempio CHF, EUR
referenceIdstringIl tuo ID ordine o di correlazione
purposestringCausale del pagamento leggibile

Gli importi sono sempre numeri interi nella più piccola unità della valuta. Inviare decimali come 89.25 è una causa frequente di errori 400.

Esempi

Request JSON (consigliata)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"
  }'
Request 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);
Envelope tipico di rispostaJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "referenceId": "ORDER-975382"
    }
  ]
}

Le risposte di successo contengono un campo status e un array data con la rappresentazione della risorsa; i campi esatti dipendono dalla risorsa. Le richieste fallite sono descritte in Errori della Merchant API.

Errori tipici di formato

  • instance inserita nel body invece che nella query string.
  • Header Content-Type mancante o non coerente con il body.
  • Importi inviati come decimali invece che come interi in unità minime.
  • Un encoding della query string diverso da quello su cui è stata calcolata ApiSignature.
  • Versioni API mischiate nello stesso flusso senza ritestare.

Prossimo passo: crea un Gateway oppure ripassa errori e rate limit.