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.
https://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16Per 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
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| instance | string | Sì | Nome della tua instance; identifica il tuo account a ogni chiamata API. |
Parametri del body
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| amount | integer | Sì | Importo del pagamento in unità minori della valuta; CHF 89.25 diventa 8925. |
| currency | string | Sì | Valuta del pagamento come codice ISO 4217, ad esempio CHF o EUR. |
| purpose | string | No | Descrizione del pagamento mostrata al cliente sulla pagina di pagamento. |
| referenceId | string | No | Identificativo del tuo ordine; viene restituito in response e webhook per associare il pagamento. |
| successRedirectUrl | string | No | Indirizzo (URL-encoded) a cui il cliente torna dopo un pagamento riuscito. |
| failedRedirectUrl | string | No | Indirizzo (URL-encoded) a cui il cliente torna dopo un pagamento fallito. |
| cancelRedirectUrl | string | No | Indirizzo (URL-encoded) a cui il cliente torna dopo l'annullamento manuale del pagamento. |
| vatRate | float | No | Aliquota IVA in percentuale applicata al pagamento. Default: null. |
| sku | string | No | Codice articolo (stock keeping unit) del prodotto pagato. |
| basket | array of objects | No | Righe prodotto con name, description, quantity, amount (unità minori) e vatRate (percento); la somma delle righe deve corrispondere ad amount. |
| psp | array of integers | No | ID dei payment provider da proporre; se omesso vengono proposti tutti i provider attivi sulla tua instance. |
| pm | array of strings | No | Identificatori dei payment method da mostrare, per limitare i metodi proposti. |
| preAuthorization | boolean | No | Autorizza e memorizza il metodo di pagamento per un addebito successivo (tipo authorization). Default: false. |
| reservation | boolean | No | Riserva l'importo per un capture successivo (tipo reservation). Default: false. |
| chargeOnAuthorization | boolean | No | Richiede preAuthorization impostato a true; addebita l'importo già durante il primo pagamento. |
| reserveOnAuthorization | boolean | No | Richiede preAuthorization impostato a true; crea una reservation a partire dall'authorization del primo pagamento. |
| fields | object | No | Dati di contatto salvati insieme al pagamento; vedi l'elenco dei campi supportati qui sotto. |
| language | string | No | Lingua della pagina di pagamento come codice ISO 639-1, ad esempio de, fr, it o en. |
| skipResultPage | boolean | No | Salta la pagina di risultato e reindirizza direttamente al tuo URL di successo o fallimento. Default: false. |
| validity | integer | No | Durata di validità del Gateway, in minuti. |
| subscriptionState | boolean | No | Gestisce il pagamento come subscription. Default: false. |
| subscriptionInterval | string | No | Intervallo di fatturazione della subscription in notazione di periodo, ad esempio P1M per un mese. |
| subscriptionPeriod | string | No | Durata totale della subscription in notazione di periodo. |
| subscriptionCancellationInterval | string | No | Periodo entro cui la subscription può essere disdetta, in notazione di periodo. |
| buttonText | array of strings | No | Etichetta personalizzata che sostituisce il testo predefinito del pulsante di pagamento. |
| lookAndFeelProfile | string | No | UUID del profilo Look and Feel da applicare alla pagina di pagamento. |
| successMessage | string | No | Messaggio personalizzato mostrato sulla pagina di risultato dopo un pagamento riuscito. |
| qrCodeSessionId | string | No | ID di sessione di un codice QR statico scansionato; rilevante solo per pagamenti TWINT con QR statico. |
| applicationFee | integer | No | Commissione in unità minori della valuta, trattenuta come application fee. |
| isPriceExclusiveVat | boolean | No | Se true, l'IVA viene aggiunta sopra ad amount invece di essere inclusa. |
| concardisOrderId | string | No | ID 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_1acustom_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
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();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.
{
"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 HTTP | Significato | Azione consigliata |
|---|---|---|
| 400 | La request non ha superato la validazione, ad esempio manca un parametro obbligatorio o un tipo è errato. | Correggi il body della request e riprova. |
| 404 | Nessun 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.