--- title: "Satispay" description: "Satispay è un'app di pagamento che permette di acquistare online e nei negozi fisici. In questa guida scoprirai come attivarla, configurarla su Fabrick Payment Orchestra e integrarla correttamente nel tuo e-commerce." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/" language: "it" --- # Satispay ## Perché scegliere Satispay Satispay è un'**app di pagamento italiana** che permette di acquistare online e nei negozi fisici, inviare e ricevere denaro, pagare buoni pasto e abbonamenti. Il pagamento si completa direttamente dall'app, senza inserire i dati di una carta. > **Approfondimento** > > Per ulteriori informazioni consulta la [documentazione ufficiale Satispay](https://developers.satispay.com/) --- ## Servizi e funzionalità disponibili tramite integrazione Fabrick L'integrazione di Satispay con Fabrick Payment Orchestra mette a disposizione le seguenti funzionalità: - **Tre prodotti di pagamento**: e-money, Meal Voucher e Fringe Benefit, in base alle abilitazioni richieste dall'esercente a Satispay. - **Pagamenti ricorrenti**: disponibili per tutti gli esercenti tramite tokenizzazione (vedi [Tokenizzazione e pagamenti ricorrenti](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#tokenizzazione-e-pagamenti-ricorrenti)). - **Buoni pasto configurabili**: possibilità di limitare o escludere l'utilizzo dei Meal Voucher sulla singola transazione (vedi [Meal Voucher](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#meal-voucher-limitare-i-massimali-della-transazione)). - **Gestione degli storni**: storni totali per tutti i prodotti, parziali e multipli per l'e-money (vedi [Limiti sugli storni](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#limiti-sugli-storni)). - **Separazione/contestualità tra autorizzazione e conferma finanziaria**: la cattura può essere contestuale all'autorizzazione oppure disposta in un momento successivo (vedi [Separazione tra autorizzazione e cattura](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#separazione-tra-autorizzazione-e-cattura)). ### Prodotti Satispay disponibili L'integrazione abilita gli esercenti a ricevere i pagamenti attraverso tre prodotti: | Prodotto | Descrizione | Abilitazione | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **e-money** | Prodotto di default di Satispay: borsellino elettronico ricaricato dal cliente tramite IBAN. | Attivo per tutti gli esercenti | | **Meal Voucher** | Buoni pasto. Il numero massimo utilizzabile in una transazione è **8 di default**, in conformità alla normativa italiana. Combinabile con e-money nella stessa transazione. | Riservato agli esercenti con MCC idonei (es. food, beverage, groceries). Richiede abilitazione esplicita da parte di Satispay e **cattura contestuale** | | **Fringe Benefit** | Benefit aziendali. Non può essere utilizzato insieme a e-money o Meal Voucher, è possibile utilizzare una sola di queste modalità di pagamento per ciascuna transazione. | Riservato agli esercenti con MCC idonei. Richiede abilitazione esplicita da parte di Satispay. Nessun vincolo sul tipo di cattura: utilizzabile anche con cattura separata | > **Abilitazione lato Satispay** > > Meal Voucher e Fringe Benefit non si attivano tramite Fabrick. Oltre a rientrare nella categoria merceologica idonea, l'esercente deve **richiedere esplicitamente a Satispay l'abilitazione** di ciascun prodotto sul proprio negozio. --- ### Separazione tra autorizzazione e cattura Per impostare o modificare la modalità di gestione delle transazioni del metodo di pagamento: 1. Accedi alla Dashboard e vai su **Impostazioni → Accedi alle configurazioni** ![Accesso alle configurazioni dalla Dashboard](https://docs.fabrick.com/assets/images/dashboard-access-configurations-f4782eb17db7b8fb6f23649ba8e3e5d7.png) 2. Una volta reindirizzato sul backoffice, vai su **Configurazioni → Ambiente** e clicca su **MOTO**: si apre un pannello laterale con l'elenco dei metodi di pagamento attivi 3. Individua il metodo di pagamento e seleziona la modalità desiderata tra **Contestuale** e **Separata** ![Configurazione MOTO per Satispay](https://docs.fabrick.com/assets/images/satispay-moto-fd42c1221dd596a908092c7393bb6294.png) > **MOTO** > > Per approfondire il funzionamento delle due modalità, consulta la sezione [separazione tra autorizzazione e cattura](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/introduction/getting-started/#moto). --- ### Limiti sugli storni Le regole di storno variano in base al prodotto Satispay utilizzato dal buyer nel pagamento ([riferimento Satispay](https://developers.satispay.com/reference/refund)): | Prodotto | Finestra temporale | Storno parziale | | ------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | | **e-money** | Entro **365 giorni** dalla creazione del pagamento | Consentito, anche multiplo fino a concorrenza del totale | | **Meal Voucher** | Solo **nello stesso giorno** della creazione del pagamento | Non consentito: solo importo totale | | **Fringe Benefit** | Entro la **fine del mese** di creazione del pagamento | Non consentito: solo importo totale | --- ## Satispay su Fabrick Payment Orchestra: attivazione e modalità di integrazione ### Richiesta di attivazione Per utilizzare Satispay è necessario disporre di un **account business Satispay**. Se non ne hai già uno, è possibile registrarsi sul [sito di Satispay](https://www.satispay.com/it-it/). Per iniziare ad accettare pagamenti con Satispay, puoi richiedere l'attivazione: - Contattando il tuo referente commerciale - Contattando l'assistenza al seguente [link](https://landing.fabrick.com/fabrick-dashboard-support) > **Shop Code e Activation Code** > > In fase di attivazione è necessario comunicare a Fabrick lo **Shop Code** e l'**Activation Code** del negozio, reperibili nella [dashboard di Satispay](https://business.satispay.com/login). In loro assenza la configurazione non può essere completata. > **Meal Voucher e Fringe Benefit** > > L'abilitazione dei **Meal Voucher** e dei **Fringe Benefit** va richiesta **direttamente a Satispay**, non a Fabrick, ed è subordinata alla categoria merceologica del negozio (vedi [Prodotti Satispay disponibili](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#prodotti-satispay-disponibili)). Una volta completate le procedure necessarie: - Fabrick abilita Satispay sul negozio e informa l'esercente. - È possibile verificare l'attivazione del metodo di pagamento all'interno della Dashboard, al percorso **Workspace → Negozi → \[Seleziona negozio] → Configurazioni** ![Satispay](https://docs.fabrick.com/assets/images/satispay-attivazione-779a55f697ccbff5100f533f77158b4e.png) > **Attivazione completata** > > Da questo momento, il tuo e-commerce è pronto per accettare pagamenti Satispay tramite Fabrick Payment Orchestra. ### Tipologie di integrazione Fabrick offre due modalità di integrazione per utilizzare Satispay: - **Integrazione hosted** ### Integrazioni supportate ✓ — Checkout Page ✓ — Pay By Link ✓ — Web Component ✓ — Lightbox Satispay viene mostrato direttamente nella pagina di pagamento Fabrick, senza alcun intervento di sviluppo lato merchant. Fabrick gestisce autonomamente la visualizzazione del metodo e l'intera fase di processamento. - **Integrazione tramite API** ### Integrazioni supportate ✓ — API Only Il redirect verso Satispay è gestito direttamente tramite API. È necessario inizializzare la transazione con `payment/create` valorizzando il campo `paymentType` con il tag **`SATISPAY`** e gestire il redirect del buyer. > **Testare Satispay in ambiente sandbox** > > Il processo per accedere all'ambiente di test è lo stesso previsto per la produzione: è possibile richiedere direttamente a Satispay l'accesso all'ambiente di test, recuperare lo **Shop Code** e l'**Activation Code** dedicati, comunicarli a Fabrick e connettersi all'ambiente di test per verificare i pagamenti. --- ## Integrazione hosted **Satispay viene mostrato direttamente nella pagina di pagamento Fabrick**, senza alcuno sviluppo aggiuntivo da parte del merchant. Fabrick gestisce autonomamente la visualizzazione del metodo e l'intera fase di processamento della transazione. Per impostare la chiamata con l'integrazione hosted, vai alla sezione [creazione della transazione e redirect verso Satispay](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#creazione-della-transazione-e-redirect-verso-satispay) e **rimuovi il campo `paymentType`** dalla chiamata `payment/create`. ![Pagina di pagamento con Satispay](https://docs.fabrick.com/assets/images/checkout-page-satispay-6f99113f8f4453eb391d41fb466076ed.png) Quando l'utente seleziona Satispay, viene reindirizzato al servizio per effettuare il login e completare il pagamento. ![Pagina di pagamento con Satispay](https://docs.fabrick.com/assets/images/satispay-2-6c53d075569249d1e5ce441d93654788.png) --- ## Integrazione tramite API Per richiedere il pagamento con Satispay utilizzando l'integrazione tramite API, è necessario inizializzare la transazione tramite `payment/create` utilizzando il tag **`SATISPAY`** nel campo `paymentType`. ### Creazione della transazione e redirect verso Satispay **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": "375.50", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["SATISPAY"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] } } ``` In risposta viene restituito nel campo `payload.userRedirect.href` il link per il redirect del buyer verso Satispay. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "b59abdc3-4eac-4660-b11b-4879d308cf09", "paymentID": "12864010053773", "userRedirect": { "href": "https://sandbox-web.axerve.com/orchestra/checkout/pbl/a/GESPAY12345/b/12864010053773/c/b59abdc3-4eac-4660-b11b-4879d308cf09" }, "qrCode": null } } ``` > **Pulsante Satispay** > > Il link restituito può essere utilizzato sotto un pulsante *Paga con Satispay*. Per il materiale grafico ufficiale e le relative condizioni d'uso, contatta il tuo referente Satispay. --- ## Funzionalità aggiuntive del metodo di pagamento ### Meal Voucher e Fringe Benefit Se il negozio è abilitato ai **Meal Voucher** e/o ai **Fringe Benefit**, questi prodotti sono **sempre attivi**: vengono applicati automaticamente da Satispay in base alla disponibilità del buyer e al wallet impostato come principale sulla sua app. Non è necessario inviare alcun parametro specifico per accettarli. #### Meal Voucher: limitare i massimali della transazione Per impostazione predefinita, ovvero **quando l'oggetto `ProductDetails` con `Type: "12"` non viene inviato**, il sistema consente l'utilizzo del numero massimo di buoni previsto, pari a **8**. L'oggetto `Type: "12"` serve quindi esclusivamente a **modificare o azzerare** questo comportamento sulla singola transazione: | Campo | Effetto | | ------------ | ----------------------------------------------------------------------- | | `Type: "12"` | Identifica la voce come configurazione Meal Voucher | | `Quantity` | Numero massimo di buoni utilizzabili nella transazione (default: **8**) | | `Price` | Importo massimo complessivo pagabile in buoni | **Limitare i buoni utilizzabili** Per consentire l'utilizzo di un numero di buoni inferiore al massimale, valorizza `Quantity` con il numero desiderato. Nell'esempio la transazione accetta al massimo **4 buoni**, per un importo complessivo in buoni non superiore a **32 €**. **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": "65.50", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["SATISPAY"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "orderDetails": { "ProductDetails": [ { "Name": "Buoni pasto", "Quantity": "4", "Price": "32", "UnitPrice": "8", "Type": "12" } ] } } ``` **Escludere i buoni pasto** Per impedire del tutto l'utilizzo dei buoni pasto sulla transazione, valorizza a `0` i campi `Quantity`, `Price` e `UnitPrice`. L'intero importo verrà pagato con e-money. **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": "65.50", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["SATISPAY"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "orderDetails": { "ProductDetails": [ { "Name": "Buoni pasto", "Quantity": "0", "Price": "0", "UnitPrice": "0", "Type": "12" } ] } } ``` **Dettagliare l'ordine** Non è necessario indicare la differenza tra l'importo pagabile in buoni e il totale della transazione: il sistema la calcola automaticamente e la copre con e-money. È però possibile aggiungere ulteriori voci `ProductDetails` se si desidera trasmettere un dettaglio più completo dell'ordine. **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": "65.50", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["SATISPAY"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "orderDetails": { "ProductDetails": [ { "Name": "Buoni pasto", "Quantity": "4", "Price": "32", "UnitPrice": "8", "Type": "12" }, { "Name": "Acquisto", "Quantity": "1", "Price": "33.50", "UnitPrice": "33.50", "Type": "1" } ] } } ``` > **Il numero effettivo di buoni lo decide Satispay** > > Questi parametri definiscono solo dei **massimali**: sarà Satispay a determinare quanti buoni utilizzare effettivamente, in base alla disponibilità sul conto del buyer. Il numero reale di buoni impiegati è noto **solo a pagamento completato**. #### Fringe Benefit: nessun parametro richiesto Per i Fringe Benefit **non esiste alcun parametro di configurazione**: se il negozio è abilitato, vengono applicati automaticamente quando il buyer ha il wallet Fringe Benefit impostato come principale. Numero e importo non possono essere indicati verso Satispay, quindi non va inviata alcuna voce `ProductDetails` dedicata. > **Storno parziale non disponibile** > > I pagamenti effettuati con Fringe Benefit possono essere stornati **solo per l'importo totale** ed entro la fine del mese di creazione del pagamento. Vedi [Limiti sugli storni](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/#limiti-sugli-storni). --- ### Tokenizzazione e pagamenti ricorrenti I pagamenti ricorrenti sono abilitati e disponibili per tutti gli esercenti. Il flusso si compone di due fasi: la creazione del token e il suo utilizzo nei pagamenti successivi. #### Creazione del token La tokenizzazione si attiva includendo il campo `satisPayDescription` nella chiamata `payment/create`. Il token può essere richiesto in due modi: - **Contestualmente a un pagamento**, valorizzando l'importo effettivo dell'ordine: la transazione viene addebitata al buyer e contemporaneamente viene generato il token - **Senza pagamento**, impostando l'importo a `0`: non viene addebitato alcun importo e la chiamata serve esclusivamente a generare il token **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": "0", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["SATISPAY"], "paymentChannel": { "channelType": ["LINK"] }, "satisPayDescription": "Abbonamento palestra" } ``` > **Campo obbligatorio per la tokenizzazione** > > Il campo `satisPayDescription` è obbligatorio per avviare un flusso di pagamenti ricorrenti: contiene la descrizione dell'accordo mostrata al buyer. In sua assenza viene elaborato un pagamento standard. In risposta viene restituito nel campo `payload.userRedirect.href` il link per il redirect del buyer verso Satispay. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f18637e4-677f-4b3f-b494-d964d276c6e9", "paymentID": "25320110053774", "userRedirect": { "href": "https://sandbox-web.axerve.com/orchestra/checkout/a/3064c1b18acb4b8d9b8a2e5c81dd398b/b/ac1dc75fef96f660fce83b75dd6c1f20f3b67d74487b937f570909c7e199aa8a28eac18b-275b-46e5-86f1-38b13abaa5e6LLSCRgadjN2jB6tm9WM7tZuBdAwDZSSNkR35Cz09khCThZf1mFk6Axzyt5CSVDm5aI7qYk0VX5KI2dKI0I985sqfS9uLoZTgUw0-JSJMtNRat7hsDgz7DzvatK8hiBf6I432mcdxE8af6oKNohNnnPE4cwpg" }, "qrCode": null } } ``` Reindirizza il buyer al link restituito: il buyer accede a Satispay e autorizza l'accordo, che riporta la descrizione indicata in `satisPayDescription`. #### Recupero del token Al completamento della transazione da parte del buyer, il token generato è disponibile tramite `GET /payment/detail`, nel campo `payload.token`: recuperalo e salvalo per i pagamenti successivi. L'esito restituito in `transactionResult` dipende dalla modalità con cui è stato richiesto il token: | Modalità | `transactionResult` | | -------------------------------------------- | -------------------------------- | | Tokenizzazione senza pagamento (importo `0`) | `WAITING` | | Tokenizzazione contestuale a un pagamento | Esito positivo della transazione | **Importo a zero** **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": "WAITING", "transactionState": "", "transactionErrorCode": "", "transactionErrorDescription": "", "bankTransactionID": "", "shopTransactionID": "", "shopTransactionID_2": "", "authorizationCode": "", "paymentID": "", "currency": "", "country": "", "company": "", "tdLevel": "", "threeDS": { "authenticationResult": null, "transDetails": null }, "events": null, "buyer": null, "risk": null, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "", "dcc": null, "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "STLBMSRUE3HYYUT9", "tokenExpiryMonth": "", "tokenExpiryYear": "", "tokenDetails": null, "fraudPrevention": null, "automaticOperation": null } } ``` **Contestuale al pagamento** **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": "4561", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "ST8248", "paymentID": "1881129911957", "currency": "EUR", "country": "", "company": "SATISPAY", "tdLevel": "", "threeDS": { "authenticationResult": null, "transDetails": null }, "events": [ { "event": { "eventtype": "AUT", "eventamount": "5.00", "eventdate": "03/09/26 15:13:43", "eventARN": "", "eventID": "", "eventReferred": "" } } ], "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "FALSE", "dcc": null, "maskedPAN": "", "paymentMethod": "SATISPAY", "productType": "", "token": "STLBMSRUE3HYYUT9", "tokenExpiryMonth": "", "tokenExpiryYear": "", "tokenDetails": null, "fraudPrevention": { "check": "FALSE", "state": "", "description": "", "order": "" }, "automaticOperation": { "type": "CAN", "date": "28/09/26 00:00:00", "amount": "5.00" } } } ``` #### Utilizzo del token per pagamenti successivi Crea la richiesta di pagamento tramite `payment/create` senza valorizzare `paymentType`. **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": "10", "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 } } ``` Nella chiamata `payment/submit` utilizza il token per processare il pagamento: - Header **`PaymentToken`**: valorizza con il `paymentToken` ricevuto dalla `payment/create` - Body: valorizza `paymentTypeDetails.satisPay.token` con il token Satispay recuperato tramite `payment/detail` **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": "SATISPAY", "paymentTypeDetails": { "satisPay": { "token": "STLBMSRUE3HYYUT9" } } } ``` --- ## Assistenza **Fabrick** - **Status page**: [https://status.fabrick.com/](https://status.fabrick.com/) - **Support**: [https://landing.fabrick.com/fabrick-dashboard-support](https://landing.fabrick.com/fabrick-dashboard-support) **Satispay** - **Docs**: [https://developers.satispay.com/](https://developers.satispay.com/) - **Business dashboard**: [https://business.satispay.com/login](https://business.satispay.com/login)