Pay By Link
Questa integrazione consente al merchant di richiedere un pagamento sfruttando i diversi canali messi a disposizione dai servizi Fabrick, con l’obiettivo di presentare al buyer la pagina di pagamento Fabrick per la scelta del metodo di pagamento, effettuare un redirect diretto verso uno specifico metodo (APM) oppure mostrare la pagina dedicata all’inserimento dei dati della carta.
La soluzione permette inoltre di definire la durata di validità della richiesta di pagamento e di configurare le URL di redirect e di notifica server to server che il sistema utilizzerà al termine della transazione.
Scegliendo questa modalità di integrazione, l’esercente può realizzare un’implementazione rapida e con un impatto minimo sui propri sistemi. Le possibilità di personalizzazione risultano più contenute rispetto a integrazioni più avanzate, in quanto l’interfaccia, i flussi di autenticazione e i redirect verso altri metodi di pagamento (APM) vengono gestiti direttamente da Fabrick.
È possibile utilizzare il servizio Pay By Link anche tramite la dashboard, che consente di utilizzare l’invio tramite SMS, offrendo così un canale aggiuntivo rispetto all’integrazione tramite API.
Questa modalità è indicata per gli esercenti che desiderano una soluzione immediata e non hanno necessità di personalizzazioni o integrazioni specifiche con i propri sistemi.
Pay By Link è ottimizzato per l'utilizzo tramite browser e non garantisce la compatibilità con canali come WebView o applicazioni native.
Per questi scenari è possibile effettuare un redirect esterno dall'app verso il link di pagamento, permettendo al cliente di completare il pagamento al di fuori del contesto applicativo, in alternativa, l'integrazione API Only offre un maggiore controllo sui flussi di autenticazione e sulla gestione dei metodi di pagamento.
Inizializzazione pagamento
Per inizializzare una richiesta di pagamento è necessario utilizzare, lato server, la chiamata payment/create.
Questa modalità garantisce un livello di sicurezza più elevato nella generazione del payload e nella gestione della API key, evitando l’esposizione di informazioni sensibili nel front‑end.
La chiamata payment/create costituisce la base della richiesta di pagamento e può essere estesa con i parametri specifici previsti dall’integrazione Pay By Link, che verranno approfonditi nelle sezioni successive.
È inoltre possibile ampliare la richiesta integrando altri servizi messi a disposizione da Fabrick, come ad esempio:
- il servizio di Risk Based Authentication
- le funzionalità di Tokenizzazione
- gli oggetti dedicati ai singoli metodi di pagamento
Questa flessibilità permette al merchant di costruire una richiesta di pagamento completa, personalizzabile e in linea con le proprie esigenze operative.
Nelle sezioni seguenti entreremo nel dettaglio riguardo l’utilizzo dell’integrazione e dei parametri da includere in chiamata per personalizzare la richiesta di pagamento.
Modalità di presentazione della pagina di pagamento
L’oggetto channelType identifica il canale, o l’insieme dei canali, attraverso cui viene presentata la richiesta di pagamento al buyer. Si tratta dell’unico parametro obbligatorio per l’utilizzo dell’integrazione Pay By Link.
Durante la creazione della richiesta, includendo in chiamata l’oggetto channelType, è possibile specificare il canale o i canali desiderati. Le opzioni disponibili sono:
LINK: utilizzato per richiedere la generazione di un URL di pagamento.QRCODE: utilizzato per ottenere una stringa Base64, da convertire in un’immagine PNG al fine di mostrare il QR Code al buyer.EMAIL: utilizzato per inviare la richiesta di pagamento tramite email. In questo caso è necessario includere e valorizzare il campobuyerEmailcon l’indirizzo email del buyer, così che il sistema possa recapitare la comunicazione.
Utilizzando più canali nella stessa richiesta, ad esempio LINK + EMAIL, il sistema genererà il link di pagamento e invierà contestualmente al buyer una email contenente la relativa richiesta di pagamento.
Pagamento tramite Link
Utilizzando l’opzione LINK, il sistema restituirà in risposta, all’interno dell’oggetto payload.userRedirect.href, l’URL di pagamento.
Questo link può essere utilizzato per effettuare il redirect del cliente oppure integrato nel frontend, ad esempio tramite un pulsante. In alternativa, può essere condiviso attraverso altri canali o inserito in comunicazioni personalizzate, come una email contenente la richiesta di pagamento
Di seguito un esempio della richiesta di pagamento con l’opzione LINK e della relativa risposta:
Request
POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
"shopLogin": "GESPAY12345",
"amount": "100",
"currency": "EUR",
"shopTransactionID": "FBK_OrderID",
"paymentChannel": {
"channelType": [
"LINK"
]
}
}
Response
{
"error": {
"code": "0",
"description": "request correctly processed"
},
"payload": {
"paymentToken": "f0419188-8a78-4918-913c-a491e4e78084",
"paymentID": "1881129911957",
"userRedirect": {
"href": "https://sandbox-web.axerve.com/orchestra/checkout/pbl/a/GESPAY12345/b/1881129911957/c/f0419188-8a78-4918-913c-b491e4e78084"
},
"qrCode": null
}
}
Periodo di validità della richiesta
Durante la creazione della richiesta è possibile definire la validità del link di pagamento tramite l’oggetto validityPeriod, inserito all’interno di paymentChannel.
Se l'oggetto validityPeriod non è valorizzato, la validità predefinita è di 48 ore.
Impostazione dell’inizio della validità
L’oggetto validityPeriod.validityStart permette di specificare il momento dal quale la richiesta di pagamento diventa attiva.
Questo oggetto accetta due parametri, ma è possibile utilizzarne solo uno alla volta per indicare l’inizio della validità della richiesta di pagamento:
minutesFromNow: definisce l'inizio della validità del pagamento dopo X minuti dalla richiesta di inizializzazione del pagamento inviata a Fabrick.UTCDateTime: definisce la data di inizio della validità del pagamento (formato UTC, es: yyyy-mm-ddThh24:mm:ss).
Se il buyer accede al link prima dell’inizio del periodo di validità, visualizzerà un avviso che indica che la richiesta di pagamento non è ancora disponibile, insieme alla data e all’ora da cui sarà possibile procedere al pagamento.
Esempio di avviso:
Impostazione della fine della validità
L’oggetto validityPeriod.validityEnd consente di indicare il momento in cui la richiesta di pagamento non sarà più valida. Anche in questo caso può essere utilizzato un solo parametro tra i seguenti:
minutesFromNow: indica la scadenza dopo X minuti dalla creazione della richiesta.UTCDateTime: definisce la scadenza tramite data e ora in formato UTC.validityMinutes: durata della validità espressa in minuti, calcolata a partire dall’inizio impostato invalidityStart.
Se il buyer accede al link dopo la scadenza, il sistema mostrerà un avviso che informa che la richiesta di pagamento non è più valida.
Esempio di avviso:
È possibile utilizzare sia validityStart che validityEnd per definire un intervallo temporale specifico.
La durata massima configurabile è 49 ore.
Di seguito un esempio di richiesta in cui il link di pagamento diventa valido dopo 10 minuti dalla generazione e rimane attivo per i successivi 50 minuti, con scadenza complessiva a 60 minuti dalla creazione.
Request
POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
"shopLogin": "GESPAY12345",
"amount": "100",
"currency": "EUR",
"shopTransactionID": "FBK_OrderID",
"paymentChannel":{
"channelType":["LINK"],
"validityPeriod":{
"validityStart":{
"minutesFromNow": "10",
"UTCDateTime": "" //yyyy-mm-ddThh24:mm:ss - es. 2025-06-29T13:14:00
},
"validityEnd":{
"minutesFromNow": "60",
"UTCDateTime": "",
"validityMinutes": "" //minutes from validity starting timestamp; can have a value only when minutesFromNow and UTCDateTime are not set
}
}
}
}
Redirect diretto verso la pagina di inserimento dei dati carta o verso un metodo di pagamento (APM)
Durante la creazione della richiesta, se lo shopLogin è abilitato per più metodi di pagmento (APM), utilizzando l'oggetto paymentType è possibile specificare nella chiamata payment/create quali metodi presentare sulla pagina, se viene specifiato solo un metodo di pagamento il sistema reindirizzerà il buyer direttamente verso il servizio senza passare dalla pagina di selezione.
Nel caso in cui si desidera invece riportare il buyer alla pagina dedicata all’inserimento dei dati della carta offerta da Farbick senza passare dalla pagina di selezione del metodo è necessario specificare in chiamata il paymentType CREDITCARD, specificando questo oggetto, se abilitati, verranno anche mostrate le modalità di pagamento tramite wallet, come ApplePay, GooglePay e Click to Pay.
Se in chiamata non viene utilizzato l'oggetto paymentType, in base alla configurazioni impostate sul backoffice di gestpay, nella pagina di pagamento verranno mostrati tutti i metodi di pagamento abilitati per lo shopLogin utilizzato e il buyer potrà scegliere con quale metodo di pagamento procedere.
I possibili valori di paymentType sono disponibili alla sezione payment type codes o in alternativa è possibile utilizzare l'endpoint GET shop/paymentMethods per verificare in tempo reale i metodi di pagamento abilitati per lo shopLogin utilizzato e filtrare la risposta per payload.paymentMethod.paymentType.
Di seguito un esempio di richiesta in cui viene specificato un solo metodo di pagamento (APM), in questo caso il buyer verrà reindirizzato direttamente alla pagina del servizio senza passare dalla pagina di selezione del metodo.
Request
POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
"shopLogin": "GESPAY12345",
"amount": "100",
"currency": "EUR",
"shopTransactionID": "FBK_OrderID",
"paymentType":["FABRICKPASS"],
"paymentChannel":{
"channelType":["LINK"]
}
}
Se invece vengono specificati più metodi di pagamento, ad esempio CREDITCARD e FABRICKPASS, il buyer verrà reindirizzato alla pagina di selezione del metodo di pagamento in cui potrà scegliere con quale metodo procedere, limitando la scelta a solo quelli specificati in chiamata.
Request
POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
"shopLogin": "GESPAY12345",
"amount": "100",
"currency": "EUR",
"shopTransactionID": "FBK_OrderID",
"paymentType":["CREDITCARD", "FABRICKPASS"],
"paymentChannel":{
"channelType":["LINK"]
}
}
Pagina di conferma dell’ordine e notifica server to server
Durante la creazione della richiesta è possibile utilizzare l’oggetto responseURLs per definire dinamicamente le URL di redirect e la URL di notifica server to server, che il sistema utilizzerà al termine della transazione, sia in caso di esito positivo sia in caso di esito negativo.
Quando l’oggetto responseURLs viene inserito nella chiamata, solo per questa transazione, il sistema non utilizzerà le URL configurate nel backoffice di Gestpay, ma applicherà quelle specificate nella richiesta. Se invece l’oggetto non è presente, verranno utilizzate le configurazioni del backoffice.
È possibile specificare anche solo una parte dei parametri. Ad esempio, se viene impostata solo la URL di notifica server to server o solo una delle URL di redirect, il sistema sovrascriverà solo i valori indicati, continuando ad utilizzare le altre URL configurate nel backoffice di Gestpay.
Di seguito un esempio di richiesta in cui vengono definite tutte le URL di redirect e la URL di notifica server to server.
Request
POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
"shopLogin": "GESPAY12345",
"amount": "100",
"currency": "EUR",
"shopTransactionID": "FBK_OrderID",
"paymentChannel": {
"channelType": ["LINK"]
},
"responseURLs": {
"buyerOK": "https://merchant-url-ok.com",
"buyerKO": "https://merchant-url-ko.com",
"serverNotificationURL": "https://merchant-url-s2s.com"
}
}
Dettaglio transazione e Notifica del Pagamento
Al termine del pagamento, il buyer viene reindirizzato alla URL di esito positivo o negativo. Contestualmente, il sistema invia anche una notifica server to server (S2S) con l’esito della transazione.
Esempio URL di redirect e notifica S2S:
https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1360119538182&paymentToken=8a901523-67a5-4aca-bbd2-c7c412934289
All’interno della URL di redirect e della notifica S2S è presente il parametro Status, che permette di identificare immediatamente lo stato del pagamento. I possibili valori sono:
OK: pagamento completato con esito positivoKO: pagamento completato con esito negativoXX: pagamento in stato sospeso, in attesa dell’esito finale.
Lo stato XX è utilizzato solo per alcuni metodi di pagamento alternativi (APM) e viene restituito quando l’esito è asincrono. In questo scenario Fabrick reindirizza il cliente alla URL di esito positivo, ma lo stato non è ancora definitivo: sarà necessario attendere una successiva notifica S2S che comunicherà l’esito finale (OK o KO).
- Se ricevi lo stato XX, non procedere con la spedizione della merce o l’erogazione del servizio.
- Attendi la notifica S2S che comunicherà l’esito finale del pagamento.
Per verificare l’esito o lo stato aggiornato della transazione è possibile utilizzare l’endpoint GET payment/detail, passando come parametro il paymentID restituito dalla chiamata payment/create o ottenuto dalla URL di redirect/notifica S2S.
Nella risposta è presente il parametro transactionResult, che indica lo stato del pagamento. I valori possibili sono:
AUTHENTICATED: pagamento autenticato (OK)APPROVED: pagamento approvato (OK)DECLINED: pagamento rifiutato (KO)PENDING: pagamento in attesa di conferma (XX)WAITING: pagamento in corso (XX)UNSUBMITTED: pagamento non è ancora inziato (XX)
Esempio di chiamata per verificare lo stato della transazione tramite paymentID.
Request
GET api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey **************** (or) PaymentToken: 8a901523-67a5-4aca-bbd2-c7c412934289
Content-Type: application/json
Response
{
"error": {
"code": "0",
"description": "request correctly processed"
},
"payload": {
"transactionType": "detail",
"transactionResult": "APPROVED",
"transactionState": "AUT",
"transactionErrorCode": "0",
"transactionErrorDescription": "Transazione correttamente effettuata",
"bankTransactionID": "1825",
"shopTransactionID": "FBK_OrderID",
"shopTransactionID_2": "",
"authorizationCode": "794183",
"paymentID": "1610469726440",
"currency": "EUR",
"country": "ITALIA",
"company": "VISA",
"tdLevel": "FULL",
"threeDS": {
"authenticationResult": {
"authenticationLevel": "2C",
"authenticationStatus": "Y",
"authStatusReason": "",
"challengeResultTransStatus": "",
"XID": "1dd3cf75-92a7-4487-abb5-b1f3cdd68f3b",
"AV": "MTIzNDU2Nzu5MDA5ODc2NTQzMjE=",
"ECI": "05",
"AVAlgorithm": "",
"threeDsVersion": "2.2.0"
},
"transDetails": {
"authData": "",
"authMethod": "02",
"authTimeStamp": "202505131259",
"acsID": "f688e45c-ff27-4ba6-a631-4b68df2dbf99"
}
},
"events": [
{
"event": {
"eventtype": "AUT",
"eventamount": "0.00",
"eventdate": "13/05/25 13:01:52",
"eventARN": "",
"eventID": "",
"eventReferred": ""
}
}
],
"buyer": {
"name": "",
"email": ""
},
"risk": {
"riskResponseCode": "",
"riskResponseDescription": ""
},
"customInfo": null,
"alertCode": "",
"alertDescription": "",
"cvvPresent": "TRUE",
"dcc": null,
"maskedPAN": "",
"paymentMethod": "VISA",
"productType": "Credit",
"token": "40G5LMXUQQ613101",
"tokenExpiryMonth": "05",
"tokenExpiryYear": "27",
"tokenDetails": {
"TokenValue": "40G5LMXUQQ613101",
"TokenExpiryMonth": "05",
"TokenExpiryYear": "27",
"TokenProvider": "AXERVE",
"CardDetails": {
"CardSuffix": "3101",
"CardExpiryMonth": "05",
"CardExpiryYear": "27",
"CardHolderName": null
},
"CardAssets": {
"CardArt": {
"Type": null,
"MediaContents": null,
"Height": null,
"Width": null
},
"BrandLogo": {
"Type": null,
"MediaContents": null,
"Height": null,
"Width": null
}
}
},
"fraudPrevention": {
"check": "FALSE",
"state": "",
"description": "",
"order": ""
},
"automaticOperation": {
"type": "CAN",
"date": "07/06/25 00:00:00",
"amount": "0.00"
}
}
}