--- title: "API Only" description: "Integra i servizi di Fabrick Payment Orchestra direttamente tramite API, senza pagine di pagamento Fabrick: form carta sul sito dell'esercente, wallet, metodi di pagamento alternativi e pagamenti con token." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/" language: "it" --- # API Only 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/) | | **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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/) · [Google Pay](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/recurring-payments/) | --- ## 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#passo-2--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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/)). > **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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/paypal/) e [Satispay](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/). > **Elenco completo dei paymentType** > > I possibili valori di **`paymentType`** sono disponibili nella sezione [payment type codes](https://api.paymentorchestra.fabrick.com/#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** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#passo-4--verifica-dellesito) vale per tutti i metodi di pagamento. > **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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/)). ### 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** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID" } ``` **Response** ```json { "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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/), i [pagamenti ricorrenti](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/recurring-payments/) o la [prevenzione frodi](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/). ### 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** 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** ```http 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 ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "CREDITCARD", "paymentTypeDetails": { "creditcard": { "number": "4012000000003101", "expMonth": "05", "expYear": "27", "CVV": "123" } } } ``` **Carta tokenizzata** 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** ```http 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 ``` ```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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/) e [Google Pay](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/). ### Passo 3 — Gestione della risposta La risposta a `payment/submit` può presentare tre scenari: **Autenticazione richiesta** 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** ```json { "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" } } } ``` **Esito immediato** Se l'autenticazione non è richiesta, l'esito viene restituito **immediatamente** in risposta alla chiamata. **Response** ```json { "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" } } } ``` **Errore** La risposta contiene l'oggetto `error` con il codice `error.code` e la descrizione `error.description`. Consulta la [lista completa degli errori](https://api.paymentorchestra.fabrick.com/#errors). **Response** ```json { "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** ```http GET /api/v1/payment/detail/{paymentID} Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "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" } } } ```