FlowAlp

Prima richiesta API

July 30, 2026

Invia la prima richiesta alla Merchant API di FlowAlp Pay: verifica le credenziali con SignatureCheck e crea un Gateway minimo con curl o PHP.

Questa guida ti porta alle prime due chiamate alla Merchant API di FlowAlp Pay: un SignatureCheck che verifica le credenziali senza creare nulla, seguito da un Gateway minimo — una sessione di checkout ospitata per un singolo pagamento. Gli esempi usano curl e l'SDK PHP con la versione API v1.16.

Prerequisiti

  • Il tuo instance name (per esempio demo-shop).
  • Un API Secret creato dalla dashboard — vedi Credenziali API.
  • Un'idea di come si autenticano le richieste — vedi Autenticazione.
  • Un ambiente backend in grado di eseguire chiamate HTTPS in uscita.
Variabili d'ambiente usate negli esempibash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Passo 1: verifica le credenziali

SignatureCheck convalida la coppia instance e API Secret. Non ha effetti collaterali: è la prima chiamata ideale e un buon health check per i deployment. Dettagli: SignatureCheck.

GEThttps://api.pay.flowalp.com/v1.16/SignatureCheck/v1.14 · v1.15 · v1.16
Verifica delle credenziali con curlbash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "x-api-key: ${FLOWALP_PAY_API_SECRET}"

Con credenziali valide ricevi HTTP 200 e uno status di successo:

RispostaJSON
{
  "status": "success",
  "data": []
}

Se l'API Secret è errato, la risposta contiene invece uno status di errore — correggi le credenziali prima di proseguire.

Passo 2: crea un Gateway minimo

Un Gateway è una sessione di checkout ospitata per un singolo pagamento. Gli importi si inviano sempre in unità minori (CHF 25.00 diventa 2500), la valuta è un codice ISO e referenceId trasporta il tuo ID ordine.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16
Creare un Gateway con curlbash
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": 2500,
    "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"
  }'
Creare un Gateway con l'SDK PHPPHP
<?php
require_once 'vendor/autoload.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(2500); // CHF 25.00 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');

try {
    $response = $client->create($gateway);
    echo $response->getLink() . PHP_EOL; // send your customer here
} catch (\Exception $e) {
    error_log('Gateway creation failed: ' . $e->getMessage());
}

Per saperne di più sull'SDK: SDK PHP.

Risposta attesa

Risposta (abbreviata)JSON
{
  "status": "success",
  "data": [
    {
      "id": 174,
      "status": "waiting",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=<hash>",
      "amount": 2500,
      "currency": "CHF"
    }
  ]
}

Reindirizza il cliente all'URL nel campo link: è la pagina di pagamento ospitata. Il Gateway parte nello stato waiting e cambia stato quando il cliente completa o annulla il pagamento. L'elenco completo dei parametri è in Creare un Gateway.

Se qualcosa va storto

Stato HTTPCausa probabileCosa fare
401 / 403Autenticazione fallita o accesso negatoRicontrolla API Secret, instance name e header x-api-key.
404Path o versione API erratiVerifica il prefisso /v1.16/ e il nome della risorsa.
405 seguito da 403Rate limit raggiuntoAttendi e riprova più tardi — vedi la guida sui rate limit.
5xxProblema temporaneo lato serverRiprova con backoff esponenziale limitato.

I payload di errore e la semantica degli status sono descritti in Errori e Rate limit.

Il redirect alla success URL non è una conferma di pagamento. Prima di evadere un ordine, verifica il pagamento lato server tramite i webhook o recuperando la transazione via API (Elencare e recuperare le Transactions).

Le prime chiamate funzionano? Esplora tutti i parametri del Gateway, configura i webhook e completa il Testing per sviluppatori prima del go-live.