FlowAlp

SDK PHP

July 30, 2026

Usa l'SDK PHP di FlowAlp Pay: installazione via Composer, configurazione del client, creazione e recupero dei Gateway, gestione errori.

L'SDK PHP incapsula la Merchant API di FlowAlp Pay: gestisce autenticazione e calcolo della firma e fornisce modelli di request/response per Gateway, Transaction, Subscription e SignatureCheck, così non costruisci mai richieste HTTP a mano.

Installazione

Installazione via Composerbash
composer require payrexx/payrexx

Il package Composer mantiene il nome tecnico dell'infrastruttura di pagamento alla base di FlowAlp Pay: installalo esattamente come mostrato. Gli esempi qui sotto usano la nomenclatura del client FlowAlp Pay; se il namespace esposto dalla versione installata dell'SDK è diverso, mantieni lo stesso identico pattern di chiamata e adegua solo il namespace.

Configura il client

Setup del clientPHP
<?php
use FlowAlpPay\FlowAlpPay;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),          // instance name, e.g. demo-shop
    getenv('FLOWALP_API_SECRET'),      // API secret from the dashboard
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',                 // platform domain
    '1.16'                             // recommended API version
);
PosizioneValoreDescrizione
1Instance nameIl sottodominio della tua pagina di pagamento (demo-shop per demo-shop.pay.flowalp.com) — vedi instance name
2API SecretEmesso sotto API & Plugins nella dashboard — vedi credenziali API
3Communication handlerMantieni il default FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER
4Dominio della piattaformapay.flowalp.com — il client ne deriva l'host API api.pay.flowalp.com
5Versione APIConsigliata 1.16; 1.14 e 1.15 restano supportate

L'API Secret dà pieno accesso al tuo account di pagamento. Caricalo da una variabile d'ambiente o da un secret manager, non committarlo mai e non usare mai l'SDK in codice esposto al browser.

Verifica le credenziali con SignatureCheck

Smoke test della connessionePHP
<?php
use FlowAlpPay\Models\Request\SignatureCheck;

try {
    $client->getOne(new SignatureCheck());
    // Instance name and API secret are valid
} catch (\FlowAlpPay\FlowAlpPayException $e) {
    // Wrong instance name or API secret
}

I dettagli dell'endpoint sono nella pagina di riferimento SignatureCheck.

Crea un Gateway

Crea un checkout ospitatoPHP
<?php
use FlowAlpPay\Models\Request\Gateway;

$gateway = new Gateway();
$gateway->setAmount(8925);            // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');
$gateway->setSuccessRedirectUrl('https://merchant.example/success');
$gateway->setFailedRedirectUrl('https://merchant.example/failed');
$gateway->setCancelRedirectUrl('https://merchant.example/cancel');

$createdGateway = $client->create($gateway);

// Send the customer to the hosted payment page
$paymentPageUrl = $createdGateway->getLink();

Reindirizza o incorpora il link di pagamento restituito e conferma il pagamento tramite i webhook: il solo redirect non è una prova. Tutti i parametri di creazione sono documentati in Create a Gateway.

Recupera un Gateway

Leggi lo stato correntePHP
<?php
use FlowAlpPay\Models\Request\Gateway;

$gateway = new Gateway();
$gateway->setId(42);

$result = $client->getOne($gateway);
$status = $result->getStatus(); // e.g. waiting, confirmed, cancelled

Il retrieve integra i webhook quando ti serve un controllo di stato on-demand — vedi Recuperare un Gateway. Lo stesso pattern create / getOne vale per gli altri modelli, ad esempio le operazioni su Transaction (elencare e recuperare, addebito, capture e rimborso) e le Subscription.

Gestisci gli errori

Intercetta le eccezioni dell'SDKPHP
<?php
use FlowAlpPay\FlowAlpPayException;

try {
    $createdGateway = $client->create($gateway);
} catch (FlowAlpPayException $e) {
    // 4xx: fix credentials, instance name or request fields - do not retry blindly
    // 5xx and rate limiting: retry with exponential backoff
    error_log('FlowAlp Pay error: ' . $e->getMessage());
}
  • Tratta le risposte 4xx come problemi di configurazione, autenticazione o validazione — vedi errori.
  • Tratta le risposte 5xx come transitorie e riprova con backoff esponenziale limitato: parti da 500 ms, raddoppia a ogni tentativo, aggiungi 0–300 ms di jitter, tetto a 30 s, massimo 5 tentativi.
  • L'API consente 600 richieste ogni 5 minuti; superata la soglia possono arrivare 405 e poi 403 — applica il backoff anche in quel caso. Dettagli: rate limit.
  • Registra status code e messaggio ripulito con il tuo riferimento di correlazione — mai l'API Secret.

Convenzioni

  • Gli importi sono interi in unità minime: CHF 89.25 → 8925.
  • Le valute usano codici ISO come CHF, EUR, USD.
  • referenceId trasporta il tuo ID ordine e ritorna negli eventi webhook.

Prossimo passo: esegui la tua prima richiesta API, poi collega i webhook per una conferma affidabile dei pagamenti.