Passa al contenuto principale

Pay By Link

Visualizza come Markdown

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.

Pay By Link

Di seguito il form di inserimento dei dati carta: Pay By Link

Pay By Link tramite dashboard

È 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.

Compatibilità

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:

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 campo buyerEmail con l’indirizzo email del buyer, così che il sistema possa recapitare la comunicazione.
Richiesta con più canali

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.

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-a491e4e78084"
        },
        "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.

Validità predefinita

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: Avviso di richiesta di pagamento non ancora valida

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 in validityStart.

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: Avviso di richiesta di pagamento scaduta

Intervallo di validità

È 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
      }
    }
  }
}

Sostituzione di una richiesta di pagamento​

Una richiesta di pagamento inviata tramite link, email o QR Code non può essere annullata: resta valida fino alla scadenza, predefinita o impostata con l'oggetto validityPeriod, e fino a quel momento il buyer può completare il pagamento.

Se è necessario sostituire una richiesta ancora valida, ad esempio per correggere l'importo o perché la stessa richiesta è stata inviata più volte, si consiglia di procedere come segue:

  1. Salva il paymentID della richiesta da sostituire, restituito dalla chiamata payment/create.
  2. Invia una nuova richiesta.
  3. Verifica gli esiti tramite la notifica S2S o la chiamata GET payment/detail: se il buyer completa il pagamento anche sulla richiesta sostituita, annulla l'autorizzazione con la chiamata payment/cancel, indicando il paymentID salvato al punto 1.
  4. Cattura solo il pagamento relativo alla nuova richiesta.
Annullamento o storno

La chiamata payment/cancel annulla un pagamento autorizzato ma non ancora catturato, quindi è utilizzabile quando l'autorizzazione e la cattura sono separate. Con la cattura contestuale il pagamento risulta già catturato: in questo caso è necessario eseguire lo storno dell'importo. La modalità attiva è quella configurata nel backoffice (vedi Gestione autorizzazione - movimentazione M.O.T.O).

Ridurre la finestra di pagamento

Per limitare il rischio di pagamenti su richieste non più necessarie, imposta con validityPeriod una durata adeguata all'utilizzo previsto del link (vedi Periodo di validità della richiesta).

Di seguito un esempio di annullamento dell'autorizzazione relativa alla richiesta sostituita.

Request

POST /api/v1/payment/cancel
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
  "shopLogin": "GESPAY12345",
  "paymentID": "1881129911957",
  "cancelReason": "Richiesta di pagamento sostituita"
}

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 pagamento (APM), è possibile utilizzare il campo paymentType nella chiamata payment/create per specificare quali metodi presentare al buyer e se mostrare o meno la pagina di selezione.

paymentTypeComportamento
Non valorizzatoMostra la pagina di selezione con tutti i metodi abilitati per lo shopLogin nel backoffice Gestpay che non richiedono campi obbligatori
Più metodi, ad esempio ["FABRICKPASS", "CREDITCARD"]Mostra la pagina di selezione limitata ai metodi indicati
Solo ["CREDITCARD"]Salta la pagina di selezione e mostra la pagina Fabrick di inserimento dei dati carta, con i wallet abilitati, come Apple Pay, Google Pay e Click to Pay
Un solo APM, ad esempio ["FABRICKPASS"]Salta la pagina di selezione: se il metodo prevede un redirect, il buyer viene reindirizzato direttamente al servizio; in caso contrario, completa il pagamento sulla pagina Fabrick
Metodi con campi obbligatori

Alcuni metodi di pagamento richiedono campi obbligatori nella chiamata payment/create. Questi metodi vengono presentati al buyer solo se la chiamata include i campi previsti; in caso contrario non compaiono nella pagina di selezione. I campi richiesti da ciascun metodo sono indicati nella relativa pagina.

Elenco completo dei paymentType

I possibili valori di paymentType sono disponibili nella sezione payment type codes. In alternativa, è possibile utilizzare l'endpoint GET shop/paymentMethods per verificare in tempo reale i metodi di pagamento abilitati per lo shopLogin utilizzato, filtrando la risposta per payload.paymentMethod.paymentType.

Di seguito un esempio di richiesta per ciascun caso.

Il campo paymentType non è presente: il buyer visualizza la pagina di selezione con tutti i metodi abilitati per lo shopLogin che non richiedono campi obbligatori.

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"]
  }
}

Pagina di conferma dell’ordine e notifica server to server​

Al termine del flusso di pagamento, completato sulla pagina di pagamento Fabrick o tramite un eventuale redirect per l’autenticazione 3D Secure o per il metodo di pagamento, il buyer viene reindirizzato alla Thank You Page. Maggiori informazioni su Thank You Page e notifica S2S in Response address.

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 positivo
  • KO: pagamento completato con esito negativo
  • XX: pagamento in stato sospeso, in attesa dell’esito finale.
Stato sospeso (XX)

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: il pagamento non è ancora iniziato (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 **************** 
Content-Type: application/json

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "detail",
        "transactionResult": "APPROVED",
        "transactionState": "AUT",
        "transactionErrorCode": "0",
        "transactionErrorDescription": "Transaction correctly processed",
        "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"
        }
    }
}