Checkout Page

Visualizza come Markdown

L’integrazione Checkout Page consente all’esercente di richiedere un pagamento utilizzando la pagina di pagamento Fabrick, nella quale il buyer può selezionare uno dei metodi di pagamento abilitati per lo shopLogin. In alternativa, è possibile effettuare un redirect diretto verso uno specifico metodo di pagamento (APM) oppure mostrare la pagina dedicata all’inserimento dei dati carta, senza passare dalla pagina di selezione.

Questa modalità consente un’implementazione rapida e con un impatto minimo sull’infrastruttura del merchant. 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.

Checkout Page

Di seguito il form di inserimento dei dati carta: Checkout Page

Checkout Page

L’integrazione Checkout Page è particolarmente indicata per gli esercenti che necessitano di una soluzione immediata, senza requisiti avanzati di personalizzazione o integrazione.

Compatibilità

La Checkout Page è ottimizzata 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 rappresenta la base della richiesta di pagamento e può essere estesa integrando i servizi messi a disposizione da Fabrick, come ad esempio:

il servizio di prevenzione frodi
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.

Redirect verso la pagina di pagamento

Per presentare la pagina di pagamento è necessario effettuare un redirect del buyer verso il link generato da Fabrick, è possibile generare il link per la richiesta di pagamento utilizzando la chiamata payment/create includendo nella richiesta l’oggetto channelType valorizzato con LINK. Il sistema in risposta restituirà all’interno dell’oggetto payload.userRedirect.href l’URL di pagamento che potrà essere utilizzata per il redirect.

Utilizzo del link

Il link restituito può essere utilizzato per effettuare il redirect del buyer, integrato nel frontend (ad esempio tramite un pulsante), oppure inserito in comunicazioni personalizzate come email o altri canali di messaggistica.

Di seguito un esempio della richiesta di pagamento:

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

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.

`paymentType`	Comportamento
Non valorizzato	Mostra 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.

Non valorizzato
Più metodi
Solo carta
Un solo APM

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

Sono indicati più metodi di pagamento, ad esempio CREDITCARD e FABRICKPASS: il buyer visualizza la pagina di selezione limitata ai soli metodi indicati.

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

È indicato solo CREDITCARD: il buyer non passa dalla pagina di selezione e visualizza direttamente la pagina Fabrick di inserimento dei dati carta, con i wallet abilitati, come Apple Pay, Google Pay e Click to Pay.

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"],
  "paymentChannel": {
    "channelType": ["LINK"]
  }
}

È indicato un solo metodo di pagamento alternativo, ad esempio FABRICKPASS: il buyer non passa dalla pagina di selezione. Se il metodo prevede un redirect, viene reindirizzato direttamente alla pagina del servizio; in caso contrario, completa il pagamento sulla pagina Fabrick.

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

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

Inizializzazione pagamento​

Redirect verso la pagina di pagamento​

Redirect diretto verso la pagina di inserimento dei dati carta o verso un metodo di pagamento (APM)​

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

Dettaglio transazione e Notifica del Pagamento​

Inizializzazione pagamento

Redirect verso la pagina di pagamento

Redirect diretto verso la pagina di inserimento dei dati carta o verso un metodo di pagamento (APM)

Pagina di conferma dell’ordine e notifica server to server

Dettaglio transazione e Notifica del Pagamento