Hosted Payment Page Orchestra - HPPO

L’integrazione Hosted Payment Page Orchestra (HPPO) 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.

hppo

Di seguito il form carta hppo

HPPO

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

Compatibilità

Hosted Payment Page Orchestra è 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-b491e4e78084"
        },
        "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 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.

Elenco completo dei paymentType

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

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