Accettare un pagamento singolo (one-time)

Il pagamento one-time è il tipo di pagamento predefinito su FlowAlp Pay: il cliente paga una sola volta e l'importo viene addebitato subito. Il modo più flessibile per accettarlo è il Gateway della Merchant API: il tuo backend crea una sessione di pagamento, FlowAlp Pay ospita il checkout e un webhook avvisa il tuo sistema quando l'incasso è avvenuto. Questa guida copre l'intero flusso, dalla creazione del Gateway all'evasione dell'ordine.

Prerequisiti#

• Un account merchant: registrati su signup.pay.flowalp.com e accedi da login.pay.flowalp.com
• Almeno un metodo di pagamento attivo — vedi Attivare i metodi di pagamento
• Il tuo instance name e le credenziali API
• Facoltativo: lo SDK PHP se il tuo backend è in PHP

Come funziona il flusso#

1. Il tuo backend crea un Gateway con importo, valuta, URL di redirect e il riferimento del tuo ordine.
2. Reindirizzi il cliente al link restituito nella risposta: il checkout hosted sulla tua pagina di pagamento tenantname.pay.flowalp.com.
3. Il cliente sceglie un metodo di pagamento (TWINT, carta, wallet, …) e paga.
4. FlowAlp Pay invia un webhook al tuo server non appena lo stato della transazione cambia.
5. Verifichi la notifica e poi evadi l'ordine.

Crea il Gateway#

Invia una richiesta POST all'endpoint Gateway. Gli importi sono sempre espressi nell'unità minima della valuta (CHF 89.25 → 8925) e referenceId deve contenere l'ID interno del tuo ordine, così puoi riconciliare il pagamento in seguito. Usa la versione API v1.16.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8925,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-1042",
    "referenceId": "ORDER-2026-1042",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Gateway;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_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-1042');
$gateway->setReferenceId('ORDER-2026-1042');
$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);
$link = $response->getLink(); // send the customer here

La risposta contiene l'id del Gateway e un link. Salva l'ID insieme all'ordine — ti servirà per recuperare il Gateway — e reindirizza il cliente al link. Tutti i parametri (IVA, basket, campi di contatto, validity, profilo grafico, …) sono documentati in Creare un Gateway.

Il cliente paga sul checkout hosted#

Sulla pagina di pagamento hosted il cliente sceglie uno dei metodi di pagamento attivi sul tuo account e completa il pagamento. Puoi limitare la scelta per un singolo pagamento con i parametri psp e pm: vedi Metodi di pagamento. Al termine il browser viene reindirizzato al tuo URL di successo, fallimento o annullamento. Preferisci l'embedding? Il checkout funziona anche in iFrame o modal window.

Conferma il pagamento server-side#

FlowAlp Pay chiama il tuo endpoint webhook a ogni cambio di stato della transazione. Un pagamento one-time è riuscito quando la transazione raggiunge lo stato confirmed. Verifica la firma del webhook prima di fidarti del payload, oppure conferma lo stato in modo indipendente recuperando il Gateway o la transazione via API.

Evadi l'ordine#

• Associa la notifica al tuo ordine tramite referenceId (o l'ID del Gateway salvato).
• Elabora ogni transazione una sola volta: i webhook possono essere reinviati, quindi rendi idempotente il tuo handler.
• Solo a quel punto spedisci la merce, attivi l'accesso o segni la fattura come pagata.