API Only

Visualizza come Markdown

L'integrazione API Only permette di utilizzare i servizi di Fabrick Payment Orchestra direttamente tramite API, senza dover utilizzare le pagine di pagamento sviluppate da Fabrick. L'esercente mantiene il controllo completo dell'esperienza di checkout: raccoglie i dati di pagamento sulle proprie pagine, gestisce i redirect richiesti dall'autenticazione e dai metodi di pagamento alternativi (APM) e invia le richieste a Fabrick per l'elaborazione.

È la modalità indicata per le realtà più strutturate, che necessitano di integrare il pagamento con il proprio backend e con la propria interfaccia, anche in contesti in cui le integrazioni hosted non sono supportate, come WebView e applicazioni native.

Integrazioni hosted e API Only

Rispetto alle integrazioni hosted (Checkout Page, Pay By Link, Lightbox, Web Component), con API Only l'interfaccia, la raccolta dei dati di pagamento e la gestione dei redirect sono a carico dell'esercente. In cambio si ottiene la massima libertà di personalizzazione del flusso.

Casi d'uso

L'integrazione API Only copre scenari diversi, che condividono le stesse chiamate di base:

Scenario	Come funziona	Dettaglio
Form carta sul sito dell'esercente	L'esercente raccoglie i dati della carta con un proprio form e li invia a Fabrick con `payment/submit`	Flusso di pagamento
Pagamento con carta tokenizzata	L'esercente invia con `payment/submit` il token di una carta salvata in precedenza, senza chiedere di nuovo i dati al buyer	Tokenizzazione
Apple Pay e Google Pay nel checkout dell'esercente	L'esercente integra gli SDK dei wallet e invia il payload restituito con `payment/submit`	Apple Pay · Google Pay
Metodi di pagamento alternativi (APM)	L'esercente inizializza la transazione indicando l'APM in `paymentType` e reindirizza il buyer verso il servizio	Logiche di presentazione dei metodi di pagamento
Pagamenti ricorrenti	L'esercente inizializza la serie con una transazione autenticata ed esegue gli addebiti successivi con il token	Pagamenti ricorrenti con carta e wallet

Logiche di presentazione dei metodi di pagamento

Con l'integrazione API Only non è presente una pagina di selezione del metodo di pagamento: è l'esercente a stabilire quale metodo utilizzare e a indicarlo nelle chiamate.

Carta e wallet: il metodo è definito dal campo paymentType della chiamata payment/submit, insieme ai dati di pagamento raccolti dall'esercente (vedi Invio dei dati di pagamento).
Metodi di pagamento alternativi (APM): il metodo è definito dal campo paymentType della chiamata payment/create, valorizzato con il tag dell'APM. Aggiungendo l'oggetto paymentChannel con channelType valorizzato a LINK, la risposta contiene in payload.userRedirect.href il link da utilizzare per il buyer: se il metodo prevede un redirect, il link porta direttamente al servizio; in caso contrario, il buyer completa il pagamento sulla pagina Fabrick.

Richiesta API per gli APM

Ogni metodo di pagamento alternativo ha campi e modalità specifiche per la richiesta tramite API: gli esempi di request e response sono riportati nella sezione Integrazione tramite API della pagina di ciascun metodo (vedi Metodi di pagamento alternativi).

Campi obbligatori e campi dedicati dei singoli APM

Alcuni APM richiedono campi obbligatori nella chiamata payment/create, da includere per poter avviare il pagamento con il metodo indicato in paymentType. Altri campi dedicati abilitano funzionalità specifiche, ad esempio la tokenizzazione, i pagamenti ricorrenti o il dettaglio dell'ordine. Le istruzioni sono riportate nella sezione Integrazione tramite API della pagina di ciascun metodo, ad esempio PayPal e Satispay.

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.

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, per l'esito positivo e per quello negativo. Con API Only le URL di redirect vengono utilizzate quando il buyer rientra da un flusso esterno, come l'autenticazione 3DS o il pagamento su un APM.

Quando l'oggetto responseURLs è presente nella chiamata, il sistema applica solo per quella transazione le URL specificate nella richiesta, al posto di quelle configurate nel backoffice Gestpay. Se l'oggetto non è presente, vengono utilizzate le configurazioni del backoffice.

È possibile specificare anche solo una parte dei parametri: se ad esempio viene impostata solo la URL di notifica server-to-server, oppure solo una delle URL di redirect, il sistema sovrascrive unicamente i valori indicati e continua a utilizzare le altre URL configurate nel backoffice 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",
    "responseURLs": {
        "buyerOK": "https://merchant-url-ok.com",
        "buyerKO": "https://merchant-url-ko.com",
        "serverNotificationURL": "https://merchant-url-s2s.com"
    }
}

Flusso di pagamento

Un pagamento API Only parte sempre dalla chiamata payment/create, che inizializza la transazione. Il passo successivo dipende dal metodo di pagamento:

Metodo	Chiamate	Presentazione al buyer
Carta e wallet	`payment/create` e `payment/submit`	L'esercente raccoglie i dati con il proprio form, o tramite gli SDK dei wallet, e li invia a Fabrick con `payment/submit`
Metodi di pagamento alternativi (APM)	`payment/create` con `paymentType` e `paymentChannel`	Il buyer viene reindirizzato al servizio tramite il link restituito dalla `payment/create` (vedi Logiche di presentazione dei metodi di pagamento)

I passi seguenti descrivono il flusso con carta e wallet. La verifica dell'esito descritta al Passo 4 vale per tutti i metodi di pagamento.

Richiesta API per gli APM

Passo 1 — Inizializzazione del pagamento

Esegui lato server la chiamata payment/create: richiede l'API key, che non deve mai essere esposta nel codice client.

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

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "paymentToken": "7ebd948a-c9ad-44c9-ac43-02b0beb55a7a",
        "paymentID": "1541109548247",
        "userRedirect": null,
        "qrCode": null
    }
}

La risposta contiene:

paymentToken, da utilizzare nell'header della chiamata payment/submit
paymentID, l'identificativo della transazione, da utilizzare per verificarne l'esito

La chiamata payment/create può essere estesa con i servizi messi a disposizione da Fabrick, ad esempio la tokenizzazione, i pagamenti ricorrenti o la prevenzione frodi.

Passo 2 — Invio dei dati di pagamento

A differenza delle integrazioni hosted, in cui il buyer viene reindirizzato su una pagina Fabrick, con API Only i dati di pagamento vengono inviati tramite la chiamata payment/submit, valorizzando l'header PaymentToken con il paymentToken ricevuto al passo precedente.

Dati carta
Carta tokenizzata

Invia i dati della carta nell'oggetto paymentTypeDetails.creditcard.

Sicurezza dei dati carta

I dati della carta possono transitare sul server dell'esercente solo se tale server è parte di un ambiente conforme alla PCI DSS, con conformità validata tramite AOC (e, se richiesto dal livello, ROC).

In assenza di conformità PCI DSS è obbligatorio raccogliere i dati tramite un form visualizzato nella sessione del buyer e inviarli a Fabrick con payment/submit lato client: in questo modo i dati carta non transitano mai sui sistemi dell'esercente.

Request

POST /api/v1/payment/submit
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
PaymentToken: 7ebd948a-c9ad-44c9-ac43-02b0beb55a7a
Content-Type: application/json

{
    "shopLogin": "GESPAY12345",
    "paymentType": "CREDITCARD",
    "paymentTypeDetails": {
        "creditcard": {
            "number": "4012000000003101",
            "expMonth": "05",
            "expYear": "27",
            "CVV": "123"
        }
    }
}

Se la carta è già stata tokenizzata in precedenza, invia il token nel campo paymentTypeDetails.creditcard.token. La chiamata può essere effettuata lato server, perché non transitano dati carta.

Request

POST /api/v1/payment/submit
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
PaymentToken: 7ebd948a-c9ad-44c9-ac43-02b0beb55a7a
Content-Type: application/json

{
    "shopLogin": "GESPAY12345",
    "paymentType": "CREDITCARD",
    "paymentTypeDetails": {
        "creditcard": {
            "token": "40ZUU8NXALR33101"
        }
    }
}

Apple Pay e Google Pay

Per i wallet il body della payment/submit contiene il payload restituito dagli SDK Apple o Google. Requisiti, configurazione e payload sono descritti nelle sezioni Integrazione tramite API delle pagine Apple Pay e Google Pay.

Passo 3 — Gestione della risposta

La risposta a payment/submit può presentare tre scenari:

Autenticazione richiesta
Esito immediato
Errore

Il campo transactionErrorCode restituisce 8006: è necessario reindirizzare il buyer alla pagina di autenticazione della sua banca, utilizzando il link presente in payload.userRedirect.href. Al termine dell'autenticazione il buyer viene reindirizzato alla URL di esito positivo o negativo.

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionErrorCode": "8006",
        "transactionErrorDescription": "Verify By Visa",
        "paymentID": "1541109548247",
        "userRedirect": {
            "href": "https://sandbox.gestpay.net/pagam/pagam3d.aspx?a=GESPAY12345&b=7ebd948a-c9ad-44c9-ac43-02b0beb55a7a&axerve3D=True&IsLightBox=False"
        }
    }
}

Se l'autenticazione non è richiesta, l'esito viene restituito immediatamente in risposta alla chiamata.

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "submit",
        "transactionResult": "OK",
        "transactionErrorCode": "0",
        "transactionErrorDescription": "Transaction correctly processed",
        "bankTransactionID": "4858",
        "shopTransactionID": "FBK_OrderID",
        "shopTransactionID_2": "",
        "authorizationCode": "428125",
        "paymentID": "1541109548247",
        "currency": "EUR",
        "country": "SINGAPORE",
        "company": "VISA",
        "tdLevel": "",
        "buyer": {
            "name": "",
            "email": ""
        },
        "risk": {
            "riskResponseCode": "",
            "riskResponseDescription": ""
        },
        "customInfo": {},
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "Y",
        "maskedPAN": "47ZUU896G2C40050",
        "paymentMethod": "",
        "productType": "Credit",
        "token": "47ZUU896G2C40050",
        "tokenExpiryMonth": "05",
        "tokenExpiryYear": "27",
        "userRedirect": {
            "href": "https://merchant-url-ok/ko.com"
        }
    }
}

La risposta contiene l'oggetto error con il codice error.code e la descrizione error.description. Consulta la lista completa degli errori.

Response

{
    "error": {
        "code": "1119",
        "description": "Credit card number with wrong length"
    },
    "payload": {}
}

Passo 4 — Verifica dell'esito

Al termine del pagamento, con qualsiasi metodo, compresi gli APM, il sistema invia una notifica server to server (S2S) con l'esito della transazione. Quando il buyer rientra da un flusso esterno, come l'autenticazione 3DS o il pagamento su un APM, viene inoltre reindirizzato alla URL di esito positivo o negativo.

Esempio di URL di redirect e notifica S2S:

https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1541109548247&paymentToken=7ebd948a-c9ad-44c9-ac43-02b0beb55a7a

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 buyer alla URL di esito positivo, ma lo stato non è ancora definitivo: è 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 o dalla 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": "1541109548247",
        "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"
        }
    }
}

Casi d'uso​

Logiche di presentazione dei metodi di pagamento​

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

Flusso di pagamento​

Passo 1 — Inizializzazione del pagamento​

Passo 2 — Invio dei dati di pagamento​

Passo 3 — Gestione della risposta​

Passo 4 — Verifica dell'esito​

Casi d'uso

Logiche di presentazione dei metodi di pagamento

Pagina di conferma dell'ordine e notifica server to server

Flusso di pagamento

Passo 1 — Inizializzazione del pagamento

Passo 2 — Invio dei dati di pagamento

Passo 3 — Gestione della risposta

Passo 4 — Verifica dell'esito