Instance name
July 30, 2026
Cos'è l'instance name in FlowAlp Pay, dove compare nel dominio della pagina di pagamento e come passarlo in ogni richiesta alla Merchant API.
L'instance — detta anche nome del tenant — è l'identificativo tecnico del tuo account merchant in FlowAlp Pay. Compare nel dominio delle tue pagine di pagamento e va inviata come query parameter instance in ogni richiesta alla Merchant API.
Dove compare l'instance
Instance: demo-shop
Tenant URL: https://demo-shop.pay.flowalp.com
API request: https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=demo-shopLa forma generale del dominio del tuo tenant è https://<instance>.pay.flowalp.com. La usi per accedere alla dashboard, e le tue pagine di pagamento ospitate sono servite sotto lo stesso dominio.
Instance e altri identificativi
Non confondere l'instance con gli altri identificativi che incontrerai nella documentazione:
| Identificativo | Cosa identifica |
|---|---|
| Instance name | Il tuo account merchant (questo articolo). |
| API Secret | La credenziale che autentica le tue richieste API — non condividerla mai. |
| Gateway ID | Una sessione di checkout creata via API. |
| Transaction ID | Una singola transazione di pagamento. |
| referenceId | Il tuo ID ordine, passato da te alla creazione di un pagamento. |
| FlowAlp Organization ID | La tua organizzazione nella FlowAlp Dashboard, fuori da FlowAlp Pay. |
Usare l'instance nella Merchant API
Ogni richiesta trasporta l'instance come query parameter:
https://api.pay.flowalp.com/v1.16/:object/:id?instance=<instance>| Parte | Descrizione |
|---|---|
| :object | La risorsa, per esempio Gateway, Transaction o Subscription. |
| :id | L'ID dell'entità, usato per GET, PUT e DELETE su una singola entità. |
| instance | Il tuo instance name — sempre nella query string. |
Nelle richieste POST tutti gli altri parametri vanno nel body; solo instance resta nella query string. Dettagli: panoramica della Merchant API e Autenticazione.
Verifica la configurazione
Abbina l'instance a un API Secret (vedi Credenziali API) e verifica la coppia con SignatureCheck:
curl --request GET \
--url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=demo-shop" \
--header "x-api-key: <api-secret>"Una risposta con stato HTTP 200 e uno status di successo conferma che instance e API Secret sono validi.
Note di sicurezza
- L'instance name è visibile negli URL e da solo non è un segreto — ma non esporlo mai insieme all'API Secret nel codice frontend.
- Le richieste con instance valida ma API Secret mancante o errato vengono rifiutate.
- Puoi registrare l'instance nei log; non registrare mai l'API Secret.
Instance individuata? Crea ora le tue credenziali API e poi invia la tua prima richiesta API.