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.
https://api.pay.flowalp.com/v1.16/Invoice/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. 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 |
|---|---|---|---|
| title | string | Sì | Titolo mostrato in cima alla pagina di pagamento hosted. |
| description | string | Sì | Testo descrittivo mostrato sulla pagina di pagamento. |
| referenceId | string | Sì | Identificativo della tua fattura o del tuo ordine; restituito in response e webhook. |
| purpose | string | Sì | Causale del pagamento mostrata al cliente. |
| amount | integer | Sì | Importo in unità minori della valuta; CHF 89.25 diventa 8925. |
| currency | string | Sì | Valuta del pagamento come codice ISO 4217, ad esempio CHF. |
| vatRate | float | No | Aliquota IVA in percentuale. Default: null. |
| psp | array of integers | No | ID dei payment provider da proporre per questo Paylink. |
| pm | array of strings | No | Identificatori dei payment method da mostrare. |
| sku | string | No | Codice articolo (stock keeping unit) del prodotto. |
| preAuthorization | boolean | No | Autorizza il metodo di pagamento per un addebito successivo invece di addebitare subito. Default: false. |
| reservation | boolean | No | Riserva l'importo per un capture successivo. Default: false. |
| name | string | No | Nome interno della pagina di pagamento; visibile solo agli amministratori. |
| fields | array of strings | No | Nomi dei campi di contatto da mostrare sulla pagina di pagamento. |
| hideFields | boolean | No | Nasconde l'intera sezione dei dati di contatto sulla pagina di pagamento. Default: false. |
| buttonText | string | No | Etichetta personalizzata per il pulsante di pagamento. |
| expirationDate | date | No | Data di scadenza del link, ad esempio 2026-08-31. |
| successRedirectUrl | string | No | URL a cui il cliente viene reindirizzato dopo un pagamento riuscito. |
| failedRedirectUrl | string | No | URL a cui il cliente viene reindirizzato dopo un pagamento fallito. |
| 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. |
| 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. |
| attachments | file | No | Allegati messi a disposizione del cliente. |
| 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. |
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
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"
}'<?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.
{
"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 HTTP | Significato | Azione consigliata |
|---|---|---|
| 400 | La 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.