FlowAlp

Creare un Gateway

July 30, 2026

Crea un checkout FlowAlp Pay con POST /Gateway/: tabella completa dei parametri, esempi curl e SDK PHP, campi della response ed errori.

Un Gateway è una sessione di checkout hosted di FlowAlp Pay per un singolo pagamento. Creala dal tuo backend quando il cliente è pronto a pagare, poi indirizzalo all'URL della pagina di pagamento restituito nella response.

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

Per le nuove integrazioni usa la versione API v1.16; v1.14 e v1.15 restano supportate. Autenticati con l'header X-API-KEY e identifica il tuo account con il query parameter instance — vedi Autenticazione e Formato delle request. Il body può essere inviato come application/json (consigliato) o application/x-www-form-urlencoded.

Request

Query parameter

ParametroTipoObbligatorioDescrizione
instancestringNome della tua instance; identifica il tuo account a ogni chiamata API.

Parametri del body

ParametroTipoObbligatorioDescrizione
amountintegerImporto del pagamento in unità minori della valuta; CHF 89.25 diventa 8925.
currencystringValuta del pagamento come codice ISO 4217, ad esempio CHF o EUR.
purposestringNoDescrizione del pagamento mostrata al cliente sulla pagina di pagamento.
referenceIdstringNoIdentificativo del tuo ordine; viene restituito in response e webhook per associare il pagamento.
successRedirectUrlstringNoIndirizzo (URL-encoded) a cui il cliente torna dopo un pagamento riuscito.
failedRedirectUrlstringNoIndirizzo (URL-encoded) a cui il cliente torna dopo un pagamento fallito.
cancelRedirectUrlstringNoIndirizzo (URL-encoded) a cui il cliente torna dopo l'annullamento manuale del pagamento.
vatRatefloatNoAliquota IVA in percentuale applicata al pagamento. Default: null.
skustringNoCodice articolo (stock keeping unit) del prodotto pagato.
basketarray of objectsNoRighe prodotto con name, description, quantity, amount (unità minori) e vatRate (percento); la somma delle righe deve corrispondere ad amount.
psparray of integersNoID dei payment provider da proporre; se omesso vengono proposti tutti i provider attivi sulla tua instance.
pmarray of stringsNoIdentificatori dei payment method da mostrare, per limitare i metodi proposti.
preAuthorizationbooleanNoAutorizza e memorizza il metodo di pagamento per un addebito successivo (tipo authorization). Default: false.
reservationbooleanNoRiserva l'importo per un capture successivo (tipo reservation). Default: false.
chargeOnAuthorizationbooleanNoRichiede preAuthorization impostato a true; addebita l'importo già durante il primo pagamento.
reserveOnAuthorizationbooleanNoRichiede preAuthorization impostato a true; crea una reservation a partire dall'authorization del primo pagamento.
fieldsobjectNoDati di contatto salvati insieme al pagamento; vedi l'elenco dei campi supportati qui sotto.
languagestringNoLingua della pagina di pagamento come codice ISO 639-1, ad esempio de, fr, it o en.
skipResultPagebooleanNoSalta la pagina di risultato e reindirizza direttamente al tuo URL di successo o fallimento. Default: false.
validityintegerNoDurata di validità del Gateway, in minuti.
subscriptionStatebooleanNoGestisce il pagamento come subscription. Default: false.
subscriptionIntervalstringNoIntervallo di fatturazione della subscription in notazione di periodo, ad esempio P1M per un mese.
subscriptionPeriodstringNoDurata totale della subscription in notazione di periodo.
subscriptionCancellationIntervalstringNoPeriodo entro cui la subscription può essere disdetta, in notazione di periodo.
buttonTextarray of stringsNoEtichetta personalizzata che sostituisce il testo predefinito del pulsante di pagamento.
lookAndFeelProfilestringNoUUID del profilo Look and Feel da applicare alla pagina di pagamento.
successMessagestringNoMessaggio personalizzato mostrato sulla pagina di risultato dopo un pagamento riuscito.
qrCodeSessionIdstringNoID di sessione di un codice QR statico scansionato; rilevante solo per pagamenti TWINT con QR statico.
applicationFeeintegerNoCommissione in unità minori della valuta, trattenuta come application fee.
isPriceExclusiveVatbooleanNoSe true, l'IVA viene aggiunta sopra ad amount invece di essere inclusa.
concardisOrderIdstringNoID ordine inoltrato all'acquirer; disponibile solo se l'opzione corrispondente è attiva nelle impostazioni del tuo payment provider.

L'oggetto fields salva i dati di contatto insieme al pagamento. Ogni voce usa il nome del campo come chiave e contiene un value; i cinque campi custom accettano anche un name localizzato. Campi supportati:

  • Identità: title, forename, surname, company
  • Indirizzo: street, postcode, place, country
  • Indirizzo di consegna: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country
  • Contatto e consensi: phone, email, date_of_birth, terms, privacy_policy
  • Campi liberi: da custom_field_1 a custom_field_5 (con etichetta localizzabile)

Se invii il body come application/x-www-form-urlencoded (ad esempio quando firmi le request con ApiSignature), mantieni tutti i parametri fields[...] raggruppati e in un ordine fisso.

Alcune opzioni dipendono dalla configurazione del tuo account: gli ID provider per psp, gli identificatori per pm, le impostazioni subscription e i parametri specifici del provider come concardisOrderId hanno effetto solo se la funzione corrispondente è attiva sulla tua instance. Se un parametro opzionale viene rifiutato, verifica la configurazione nella dashboard o contatta il supporto.

Esempio di request

Creare 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"}
    }
  }'
Creare 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();

Response

Una chiamata riuscita restituisce HTTP 200 con l'envelope mostrato sotto: status vale success e data contiene il nuovo Gateway come unico elemento. Salva l'id, poi reindirizza il cliente verso link. Un Gateway appena creato parte sempre con status 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"
    }
  ]
}

Non considerare mai il redirect verso successRedirectUrl una prova di pagamento. Conferma ogni pagamento con i webhook oppure leggi lo stato attuale con Recuperare un Gateway.

Errori

Status HTTPSignificatoAzione consigliata
400La request non ha superato la validazione, ad esempio manca un parametro obbligatorio o un tipo è errato.Correggi il body della request e riprova.
404Nessun risultato per la request, ad esempio perché il nome della instance è errato.Controlla il query parameter instance e l'URL dell'endpoint.

Le response di errore usano l'envelope {"status": "error", "message": "..."}; il modello generale è descritto in Errori. L'API consente 600 request ogni 5 minuti — vedi Rate limit.

Prossimi passi: incorpora la pagina di pagamento con il Checkout embedding, segui il flusso completo in Accettare un pagamento singolo, oppure approfondisci la pre-autorizzazione e gli abbonamenti.