FlowAlp

Creare un Paylink

July 30, 2026

Crea un Paylink FlowAlp Pay con POST /Invoice/: un link di pagamento da inviare via e-mail o codice QR. Parametri, esempi ed errori.

Un Paylink è una pagina di pagamento hosted di FlowAlp Pay con configurazione fissa: la crei una volta e poi la condividi — via e-mail, in una fattura PDF, come codice QR o in chat. Il cliente apre il link e paga; non serve alcun codice sul tuo sito. Nella Merchant API la risorsa sottostante si chiama Invoice.

POSThttps://api.pay.flowalp.com/v1.16/Invoice/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. 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
titlestringTitolo mostrato in cima alla pagina di pagamento hosted.
descriptionstringTesto descrittivo mostrato sulla pagina di pagamento.
referenceIdstringIdentificativo della tua fattura o del tuo ordine; restituito in response e webhook.
purposestringCausale del pagamento mostrata al cliente.
amountintegerImporto in unità minori della valuta; CHF 89.25 diventa 8925.
currencystringValuta del pagamento come codice ISO 4217, ad esempio CHF.
vatRatefloatNoAliquota IVA in percentuale. Default: null.
psparray of integersNoID dei payment provider da proporre per questo Paylink.
pmarray of stringsNoIdentificatori dei payment method da mostrare.
skustringNoCodice articolo (stock keeping unit) del prodotto.
preAuthorizationbooleanNoAutorizza il metodo di pagamento per un addebito successivo invece di addebitare subito. Default: false.
reservationbooleanNoRiserva l'importo per un capture successivo. Default: false.
namestringNoNome interno della pagina di pagamento; visibile solo agli amministratori.
fieldsarray of stringsNoNomi dei campi di contatto da mostrare sulla pagina di pagamento.
hideFieldsbooleanNoNasconde l'intera sezione dei dati di contatto sulla pagina di pagamento. Default: false.
buttonTextstringNoEtichetta personalizzata per il pulsante di pagamento.
expirationDatedateNoData di scadenza del link, ad esempio 2026-08-31.
successRedirectUrlstringNoURL a cui il cliente viene reindirizzato dopo un pagamento riuscito.
failedRedirectUrlstringNoURL a cui il cliente viene reindirizzato dopo un pagamento fallito.
subscriptionStatebooleanNoGestisce il pagamento come subscription. Default: false.
subscriptionIntervalstringNoIntervallo di fatturazione della subscription in notazione di periodo, ad esempio P1M.
subscriptionPeriodstringNoDurata totale della subscription in notazione di periodo.
subscriptionCancellationIntervalstringNoPeriodo entro cui la subscription può essere disdetta, in notazione di periodo.
attachmentsfileNoAllegati messi a disposizione del cliente.
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.

Alcune opzioni dipendono dalla configurazione del tuo account: gli ID provider per psp, gli identificatori per pm, le impostazioni subscription, gli attachments 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 Paylink (cURL)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Invoice/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Invoice INV-2026-0042",
    "description": "Consulting services, June 2026",
    "referenceId": "INV-2026-0042",
    "purpose": "Invoice INV-2026-0042",
    "amount": 8925,
    "currency": "CHF",
    "expirationDate": "2026-08-31",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed"
  }'
Creare un Paylink (SDK PHP)PHP
<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Paylink;

$client = new FlowAlpPay(
    getenv('FLOWALP_PAY_INSTANCE'),
    getenv('FLOWALP_PAY_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$paylink = new Paylink();
$paylink->setTitle('Invoice INV-2026-0042');
$paylink->setDescription('Consulting services, June 2026');
$paylink->setReferenceId('INV-2026-0042');
$paylink->setPurpose('Invoice INV-2026-0042');
$paylink->setAmount(8925); // CHF 89.25 in minor units
$paylink->setCurrency('CHF');
$paylink->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$paylink->setFailedRedirectUrl('https://shop.example.com/payment/failed');

$response = $client->create($paylink);

// Share this URL by e-mail or render it as a QR code.
$paylinkUrl = $response->getLink();

Response

Il nuovo Paylink viene restituito nell'envelope di successo. Invia al cliente l'URL contenuto in link — oppure costruisci l'URL a partire da hash — e salva id e referenceId nel tuo sistema. Per collegare un pagamento in arrivo al Paylink affidati a link o hash, non al solo referenceId.

200 OKJSON
{
  "status": "success",
  "data": [
    {
      "id": 57,
      "hash": "f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "referenceId": "INV-2026-0042",
      "link": "https://demo-shop.pay.flowalp.com/?payment=f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "title": "Invoice INV-2026-0042",
      "description": "Consulting services, June 2026",
      "purpose": "Invoice INV-2026-0042",
      "amount": 8925,
      "currency": "CHF",
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Errori

Status HTTPSignificatoAzione consigliata
400La request non ha superato la validazione, ad esempio manca un parametro obbligatorio come title o referenceId.Correggi il body della request e riprova.

Le response di errore usano l'envelope {"status": "error", "message": "..."} — vedi Errori e Rate limit.

Correlati: la guida Pay link e codici QR, la verifica dei pagamenti con Recuperare ed elencare i Paylink, la gestione del ciclo di vita in Aggiornare ed eliminare un Paylink e la conferma dei pagamenti via webhook.