Pagamenti ricorrenti con carta

Le transazioni inizializzate dall’esercente (Merchant Initiated Transactions – MIT) sono tipiche in contesti caratterizzati da modelli di business in cui i pagamenti vengono effettuati in momenti successivi rispetto al momento dell’acquisto.

In questi scenari, l’acquirente autorizza l’esercente ad eseguire addebiti futuri, accettando i termini e le condizioni definiti nell’accordo contrattuale tra le parti.

Esempi di utilizzo

Alcuni esempi sono: il pagamento di bollette, gli abbonamenti e i modelli di business basati su servizi a consumo.

Per la corretta gestione di questa tipologia di pagamenti è necessario distinguere e utilizzare correttamente le seguenti tipologie di transazione:

Customer Initiated Transaction (CIT)
Rappresenta la prima transazione nel flusso dei pagamenti ricorrenti.
Al cliente viene richiesto di copmletare l’autenticazione forte (Strong Customer Authentication – SCA), al fine di verificare l’identità del pagatore e generare l’identificativo di riferimento necessario per il processamento delle transazioni successive, che avverranno in assenza del cliente.
Merchant Initiated Transaction (MIT)
Sono transazioni avviate dall’esercente senza la presenza dell’acquirente, in conformità agli accordi e alle condizioni precedentemente definiti e accettati dal cliente.

Ambito normativo

Le transazioni MIT sono considerate out of scope rispetto alla PSD2 e, pertanto, non richiedono l’autenticazione a due fattori.

Linee guida per l'integrazione

Fabrick Payment Orchestra supporta due tipologie di Merchant Initiated Transaction (MIT). Per tutte e due le tipologie è prevista una transazione iniziale, a cui faremo riferiremo come First (CIT), che necessita di autenticazione del cliente (SCA).

A seguito della transazione iniziale, viene eseguita da parte dell'esercente una serie di transazioni successive, chiamate Next (MIT), che vengono addebitate al cliente in base alla sottoscrizione del servizio, intesa come l’accordo contrattuale tra le parti.

Le transazioni Next condividono i seguenti requisiti:

Deve essere presente un accordo tra esercente e acquirente che autorizzi l’esercente ad effettuare addebiti a carico del cliente.
Ogni transazione Next deve includere in chiamata il riferimento alla transazione iniziale First.
Ogni transazione Next deve essere presentata con lo stesso shopLogin utilizzato per la transazione First, in quanto non è possibile fare riferimento a una First generata su uno shopLogin differente.
Non è possibile presentare una transazione Next la cui prima transazione First è stata cancellata, in quanto la catena ricorrente non risulterebbe più valida.
La transazione First a cui fanno riferimento le Next successive deve essere autenticata tramite Strong Customer Authentication (SCA).

Tokenizzazione per transazioni Next

Per consentire il processamento delle transazioni in cui il cliente non è in sessione (MIT), durante la transazione iniziale (CIT) deve essere richiesto il servizio di tokenizzazione, al fine di ottenere dal sistema il token della carta da utilizzare per le transazioni successive.

Transazioni ricorrenti

Le transazioni ricorrenti sono indicate nei casi in cui l’importo del pagamento è fisso e la frequenza degli addebiti è definita da una periodicità costante.
Questa tipologia è tipicamente utilizzata per modelli di business basati su abbonamenti, come ad esempio l’erogazione di servizi digitali o contenuti a pagamento.

Le transazioni ricorrenti consentono una gestione strutturata e prevedibile dei pagamenti, risultando ideali per scenari in cui importo e scadenze sono noti e invariabili nel tempo.

Importo e periodicità costanti
Le transazioni ricorrenti prevedono addebiti con importo fisso e una pianificazione definita delle scadenze.
Transazioni non programmate

Le transazioni non programmate sono caratterizzate da importi e periodicità variabili.
Questa tipologia è particolarmente indicata per modelli di business basati su pagamenti a consumo, per la gestione di no-show fees e per l’applicazione di penali, ad esempio in caso di danni a beni noleggiati.

Rispetto alle transazioni ricorrenti, questa modalità di integrazione offre maggiore flessibilità, presentando un numero inferiore di vincoli in termini di configurazione e gestione dei pagamenti.

Importo e periodicità variabili
Le transazioni non programmate consentono di addebitare importi variabili senza una pianificazione fissa delle scadenze.

Flusso First (CIT)

Per inizializzare un pagamento ricorrente, il cliente deve inserire i dati della propria carta all’interno della pagina di pagamento Fabrick oppure tramite una pagina di pagamento personalizzata messa a disposizione dall’esercente sul proprio sito.

Qualora la carta sia già stata tokenizzata in una fase precedente, è possibile utilizzare il token per processare la transazione, evitando di richiedere un nuovo inserimento dei dati da parte del cliente.

Impostazione della tipologia di transazione

Per indicare al sistema che una transazione fa parte di una serie di pagamenti ricorrenti, e in particolare che si tratta della prima transazione, la First, è necessario aggiungere in chiamata l'oggetto transDetails e valorizzare il campo type con uno dei seguenti valori:
- 01F – Transazioni ricorrenti
- 03F – Transazioni non programmate

Transazioni di Tipo First

In base alla tipologia selezionata per i pagamenti ricorrenti, di seguito sono riportati i campi da valorizzare in chiamata, da utilizzare in aggiunta ai campi obbligatori previsti per effettuare la chiamata payment/create, necessari per il corretto processamento della transazione.

Transazioni ricorrenti

Oggetto	Campo	Descrizione
`transDetails`	`type`	Valorizzare con `01F` per indicare l’inizializzazione di una ricorrenza con importo e periodicità costanti
`transDetails`	`authenticationAmount`	Importo massimo atteso secondo i termini e le condizioni dell’accordo tra le parti
`transDetails.recurringTransaction`	`expiry`	Data di scadenza dell’accordo
`transDetails.recurringTransaction`	`frequency`	Numero minimo di giorni tra un pagamento e il successivo

Transazioni non programmate

Oggetto	Campo	Descrizione
`transDetails`	`type`	Valorizzare con `03F` per indicare l’inizializzazione di una ricorrenza con importo e/o periodicità variabili
`transDetails`	`authenticationAmount`	Importo massimo atteso secondo i termini e le condizioni dell’accordo tra le parti

Per tutte e due le tipologie di transazioni, in risposta alla chiamata payment/create, Fabrick restituisce l’identificativo paymentID. Al termine della transazione, se conclusa con esito positivo, il paymentID potrà essere utilizzato come riferimento per le successive transazioni Next.

Gestione dell’importo iniziale

Non è raro che un servizio preveda un periodo di prova gratuito o un addebito posticipato, processato quindi in un momento successivo rispetto alla fase in cui il cliente è in sessione. Per gestire correttamente questo scenario, è possibile valorizzare il campo amount della transazione iniziale con importo paro a zero.

Quando l’importo iniziale è pari a 0,00 la richiesta viene definita ASI ed è necessario includere l’oggetto authenticationAmount, che deve essere valorizzato con l’importo massimo previsto dagli accordi contrattuali per i pagamenti successivi. Questo valore definisce l’importo massimo autorizzato per le future transazioni ricorrenti Next.

L’importo indicato in authenticationAmount potrebbe essere visualizzato dal compratore durante il processo di autenticazione, in base alle configurazioni della banca.
In alternativa, potrebbe essere mostrato l’importo indicato nel campo amount.

Importo massimo autorizzato
Se l’oggetto authenticationAmount non è valorizzato, se viene valorizzato solo il campo amount, oppure se l’importo indicato in amount risulta superiore a quello presente in authenticationAmount, il sistema utilizzerà l’importo del campo amount come importo massimo autorizzato per le transazioni ricorrenti successive e, contestualmente, l’addebito iniziale verrà effettuato per l’importo indicato in amount.

ASI (Account Status Inquiry)
Questa operazione è finalizzata alla verifica della carta: non è possibile movimentare o cancellare la transazione.

Limite acquirer
È possibile richiedere una transazione (ASI) iniziale con importo pari a 0,00 € solo utilizzando Banca Sella o Shift4 come acquirer.
Gestione dei dati della carta e del token

Una transazione First può essere presentata in due modalità, a seconda che il token della carta sia già disponibile oppure no.
- Con token
  
  Se il token della carta è già stato generato in precedenza, non è necessario mostrare la pagina di pagamento al cliente.
  In questo caso la transazione First può essere gestita interamente lato server, utilizzando l’integrazione API Only, effettuando il redirect del compratore verso la pagina di autenticazione 3DS, quando richiesto.
  
  Questa modalità è ideale quando la carta è già stata registrata (tokenizzata) durante una transazione precedente.
- Senza token
  
  Se il token non è disponibile, è necessario mostrare la pagina di pagamento Fabrick, oppure mettere a disposizione un form sul sito per permettere al cliente di inserire i dati di pagamento.
  
  Durante la transazione First verrà richiesto anche il servizio di tokenizzazione, in modo da ottenere un token da utilizzare per le successive transazioni Next.
  
  Per attivare il processo di tokenizzazione è necessario aggiungere nella chiamata payment/create il campo requestToken valorizzato con MASKEDPAN.
  
  Una volta completata la transazione e la relativa autenticazione, interrogando il sistema tramite l'API payment/detail, sarà possibile recuperare il token generato e associarlo al buyer e al servizio attivato.
note
- Realizza la tua pagina di pagamento personalizzata utilizzando le API Only.
- Su questa pagina puoi trovare maggiori informazioni sul servizio di Tokenizzazione.
Informativa obbligatoria al buyer
Il flusso First (CIT) richiede la tokenizzazione della carta: il buyer deve quindi essere informato che i suoi dati verranno tokenizzati prima dell'invio della transazione.
- Se raccogli i dati carta tramite una soluzione Fabrick (pagina di pagamento o Web Component), l'informativa è già gestita: il messaggio viene mostrato automaticamente sulla pagina.
- Se utilizzi una pagina di pagamento personalizzata (API Only), l'informativa è a carico dell'esercente.
I messaggi mostrati dalle soluzioni Fabrick nella pagina sono descritto alla sezione Tokenizzazione.
Gestione dell’autenticazione

Durante il flusso della transazione First è sempre richiesta l’autenticazione forte del cliente (SCA).
Non è possibile richiedere alcuna esenzione, indipendentemente:
- dalla modalità di integrazione utilizzata
- dalla disponibilità del token della carta
Modalità di gestione dell’autenticazione
- Pagina di pagamento Fabrick
  Se l’integrazione è tramite la pagina di pagamento Fabrick, la gestione dell’autenticazione del cliente viene effettuata direttamente da Fabrick.
- Integrazione API Only
  Nel caso di integrazione API Only, la gestione del redirect per l’autenticazione ricade sull’esercente.
  A seguito della chiamata payment/submit:
  - Se la carta supporta i protocolli di autenticazione: Il sistema restituisce l’errore 8006 (Verify By Visa), richiedendo l’autenticazione del titolare della carta. Utilizzando il link presente nel campo payload.userRedirect.href è possible reindirizzare il cliente verso i protocolli di autenticazione della sua banca.
  - Se la carta non supporta i protocolli di autenticazione: Otterrai immediatamente l’esito finale della transazione senza necessità di chiamare payment/detail per ulteriori informazioni.
Autenticazione obbligatoria
L’autenticazione del cliente rappresenta un passaggio fondamentale per la sottoscrizione e la validazione della ricorrenza.
Conclusione del pagamento

Una volta che il cliente ha completato la fase di autenticazione con la propria banca, verrà reindirizzato verso la URL di esito positivo/negativo definita dall’esercente

Allo stesso tempo, il sistema invia anche una notifica server‑to‑server (S2S) al backend dell’esercente, contenente l’esito finale dell’operazione.

Questo permette all’esercente di aggiornare lo stato del pagamento anche se il cliente non torna al sito.

Dopo la conclusione del pagamento, è possibile utilizzare l’endpoint payment/detail per ottenere tutte le informazioni della transazione e salvare i dati necessari a gestire eventuali pagamenti ricorrenti Next.

Una volta completata la transazione First e salvati i dati necessari, è possibile procedere con la cattura oppure con lo storno dell’importo autorizzato.
- Transazioni con importo pari a 0,00 € (ASI)
  
  Nel caso in cui l’importo della transazione First è pari a 0 (ASI), il sistema non consente la cancellazione della transazione.
  La cancellazione interromperebbe la catena di pagamento e impedirebbe l’esecuzione delle future transazioni Next.
- Transazioni con importo maggiore di zero e shopLogin con MOTO separato
  
  Quando l’importo della transazione First è maggiore di zero e lo shopLogin è configurato con MOTO separato, è altrettanto importante non cancellare la transazione tramite API payment/cancel o Dashboard Fabrick. La cancellazione renderebbe non valida la transazione First, bloccando così la possibilità di eseguire le future ricorrenze Next.
  
  Se è necessario rimborsare l’importo al cliente,è possibile catturare l'intero importo della transazione, e successivamente esegure uno storno. In questo modo la catena delle ricorrenze rimane attiva, consentendo la corretta esecuzione delle successive transazioni Next.
Attenzione
È fondamentale non cancellare mai la transazione First (né tramite API payment/cancel né tramite dashboard).
La cancellazione renderebbe impossibile eseguire le transazioni ricorrenti Next.

Integrazione

Pagina di pagamento - Non programmate - Senza token#

Per inizializzare un pagamento ricorrente utilizzando la Pagina di pagamento Fabrick

Creazione della richiesta di pagamento

Utilizza la chiamata payment/create lato server per generare la richiesta di pagamento, assicurandoti di includere nel body il campo requestToken valorizzato con MASKEDPAN per richiedere la tokenizzazione della carta.
Questo approccio garantisce la sicurezza nella generazione del payload della richiesta e nell'utilizzo della API key.

Dati principali da salvare per le ricorrenze future:
- authenticationAmount
modalità di integrazione
In base alla modalità di integrazione scelta, la pagina di pagamento può essere presentata tramite il servizio Pay By Link oppure attraverso la soluzione Lightbox o Web Components.
Nell’esempio riportato di seguito viene utilizzata la modalità Pay By Link; in caso di integrazione tramite Lightbox o Web Components, è sufficiente rimuovere l’oggetto paymentChannel dalla chiamata.

POST payment/create – First 03F

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": "0",
    "currency": "EUR",
    "shopTransactionID": "FBK-C03F_OrderID",
    "paymentChannel": { "channelType": ["LINK"] }, // Payment link request (PBL)
    "paymentType": ["CREDITCARD"], // Payment request by card only
    "requestToken": "MASKEDPAN", // Request token generation
    "transDetails": {
        "type": "03F",
        "authenticationAmount": "100"
    }
}
```

Presentazione della pagina di pagamento

In risposta alla chiamata payment/create , in base all’integrazione utilizzata, otterrai:

Lightbox o Web Components

paymentToken
paymentID

Pay By Link

paymentToken
paymentID
href (link per il redirect del cliente verso la pagina di pagamento)

I valori restituiti dalla chiamata sono necessari per:

presentare la pagina di pagamento tramite integrazione Lightbox o Web Components
gestire il redirect del cliente verso la pagina di pagamento, utilizzando il link presente in payload > userRedirect > href tramite integrazione Pay By Link
utilizzare la chiamata payment/detail per verificare l’esito del pagamento e recuperare le informazioni relative al token

Il sistema restituisce i valori paymentToken e paymentID, che devono essere utilizzati nel JavaScript dedicato per mostrare la pagina di pagamento.

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "paymentToken": "8a901523-67a5-4aca-bbd2-c7c412934289",
        "paymentID": "1360119538182",
        "userRedirect": null,
        "qrCode": null
    }
}

Integrazione Pay By Link

Il link da utilizzare per reindirizzare il cliente alla pagina di pagamento è presente nel campo: payload > userRedirect > href.

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "paymentToken": "8a901523-67a5-4aca-bbd2-c7c412934289",
        "paymentID": "1360119538182",
        "userRedirect": {
            "href": "https://sandbox-web.axerve.com/orchestra/checkout/a/dc1e181fe487435c86a09120550327a9/b/925e8ec8839a1baf2da2d49f5ecf87cfdfd671d0486f0c9f5932b5e3f751015cdbd5cf51-3a24-4a5b-93d9-999b5b191f54Pbt52obGzvypZVa-GFVGk3cRg9u-lKsJhyN-QqmbrdW3e6kF1HuES-vViOdWiDq18MhptroRU9fSvbyJHOQxxbOyEYB43hLm7PlaAjHOJeG58RIRuKBMwY40yyMjt-JmYZuWOGxbUnbNfRjYw2vKFro5sZU3"
        },
        "qrCode": null
    }
}

Verifica e completamento del pagamento

Dopo che il compratore ha completato il pagamento:

Integrazione Pay By Link
L’utente viene reindirizzato alla URL di esito positivo/negativo.
Integrazione Web Components
L’utente viene reindirizzato alla URL di esito positivo/negativo.
Integrazione Lightbox
- Se utilizzi l’oggetto di callback, il sistema non effettua il redirect: nell’oggetto ricevuto sarà disponibile la URL nel campo responseURL.
- Se non utilizzi l’oggetto di callback, il sistema effettua in automatico il redirect alla URL di esito positivo/negativo.

Per tutte due le tipologie di integrazione il sistema invierà contestualmente anche una notifica S2S contenente l’esito del pagamento, insieme ai dati paymentToken e paymentID.

Esempio di URL di redirect e notifica S2S:

https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1360119538182&paymentToken=8a901523-67a5-4aca-bbd2-c7c412934289

Utilizza l'API payment/detail per verificare l’esito del pagamento e ottenere il token della carta.

Dati principali da salvare per le ricorrenze future:

paymentID
TokenValue

Confermato l'esito positivo del pagamento è possibile procedere con la cattura o lo storno della transazione e la gestione del token.

`GET payment/detail` – Esito pagamento + informazioni token

Request

GET /api/v1/payment/detail/1360119538182 (PaymentID)
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey **************** (or) PaymentToken: 8a901523-67a5-4aca-bbd2-c7c412934289
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": "492",
        "shopTransactionID": " FBK-C03F_OrderID",
        "shopTransactionID_2": "",
        "authorizationCode": "188190",
        "paymentID": "1360119538182",
        "currency": "EUR",
        "country": "ITALIA",
        "company": "VISA",
        "tdLevel": "FULL",
        "threeDS": {
            "authenticationResult": {
                "authenticationLevel": "2C",
                "authenticationStatus": "Y",
                "authStatusReason": "",
                "challengeResultTransStatus": "",
                "XID": "12e6e4ce-8ccc-49f9-b5a4-18b486f1d29d",
                "AV": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
                "ECI": "05",
                "AVAlgorithm": "",
                "threeDsVersion": "2.1.0"
            },
            "transDetails": {
                "authData": "",
                "authMethod": "02",
                "authTimeStamp": "202407111313",
                "acsID": "48a413bf-fe27-4de2-a39e-dc6039e4aef7"
            }
        },
        "events": [
            {
                "event": {
                    "eventtype": "AUT",
                    "eventamount": "0.00",
                    "eventdate": "11/07/24 13:13:56",
                    "eventARN": "",
                    "eventID": "",
                    "eventReferred": ""
                }
            }
        ],
        "buyer": {
            "name": "",
            "email": ""
        },
        "risk": {
            "riskResponseCode": "",
            "riskResponseDescription": ""
        },
        "customInfo": null,
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "TRUE",
        "dcc": null,
        "maskedPAN": "",
        "paymentMethod": "VISA",
        "productType": "Credit",
        "tokenDetails": {
            "TokenValue": "40ZUU8NXALR33101",
            "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": "05/08/24 00:00:00",
            "amount": "0"
        }
    }
}

Flusso Next (MIT)

Le transazioni MIT rappresentano i pagamenti successivi alla transazione iniziale (First) e vengono eseguiti in assenza del cliente, sulla base dell’autorizzazione precedentemente rilasciata durante la transazione First.

L’esecuzione delle transazioni ricorrenti Next non è gestita automaticamente da Fabrick, è l’esercente che deve programmare, avviare e gestire ciascun addebito ricorrente, nel rispetto degli accordi contrattuali e delle condizioni accettate dal cliente durante la sottoscrizione del servizio.

Impostazione della tipologia di transazione

Per indicare al sistema che una transazione rappresenta un pagamento successivo di una ricorrenza, è necessario aggiungere in chiamata l'oggetto transDetails e valorizzare il campo type con uno dei seguenti valori:
- 01N – Transazioni ricorrenti
- 03N – Transazioni non programmate
Transazioni di tipo Next

Per gestire l’incasso di un pagamento ricorrente tramite una transazione Next, nella chiamata payment/create è necessario:
- impostare il parametro type con il valore corretto;
- includere il riferimento alla transazione iniziale autenticata (First).
Per fornire al sistema il paymentID della transazione First, è necessario aggiungere l’oggetto transDetails.previousTransDetails e valorizzare il campo paymentID, oltre ai campi obbligatori previsti per l’operazione payment/create.

Campi richiesti per l’associazione alla transazione First

Oggetto Campo Descrizione
transDetails type Valorizzare con 01N / 03N
transDetails.previousTransDetails paymentID Identificativo della transazione First (CIT)

ShopLogin da utilizzare per indicare la First
Il paymentID della transazione First è valido esclusivamente sullo shopLogin su cui la transazione è stata generata.
Non è quindi possibile presentare una transazione Next su uno shopLogin diverso, il riferimento alla First non verrebbe risolto e la transazione non potrebbe essere processata.
Se è necessario incassare la ricorrenza su un altro shopLogin, occorre generare una nuova transazione First (CIT) autenticata sul nuovo shopLogin e utilizzare il paymentID ottenuto come riferimento per tutte le Next successive.

Per le transazioni Next il cliente non è presente e non può reinserire i dati della carta.
Per questo motivo, oltre a indicare nella chiamata payment/create il riferimento alla transazione First, nella chiamata payment/submit è necessario utilizzare il token della carta generato (o utilizzato) durante la transazione First.

L’utilizzo del token consente al sistema di processare correttamente la transazione, evitando di richiedere nuovamente i dati di pagamento al compratore.

Nella chiamata payment/submit, il token deve essere inserito all’interno dell’oggetto paymentTypeDetails.creditcard, valorizzando il campo token.

Campi richiesti per l’invio del token nella payment/submit

Oggetto Campo Descrizione
paymentTypeDetails.creditcard token Token della carta utilizzata durante la transazione First
Gestione della transazione

Per questa tipologia di transazione non è necessario presentare nuovamente la pagina di pagamento al cliente. Una volta completata con successo la transazione iniziale First, il sistema dispone già di tutte le informazioni necessarie per gestire le ricorrenze successive (Next).

In casi eccezionali, la banca del cliente potrebbe richiedere una nuova autenticazione. In tal caso, il sistema restituirà in risposta alla chiamata payment/submit l’errore 8026 – Soft Decline.
Quando si verifica questa condizione, è necessario contattare il cliente e inizializzare una nuova transazione First, al fine di ottenere un nuovo identificativo (paymentID) da utilizzare per le future transazioni Next.

Nota operativa
Per l’esecuzione delle transazioni MIT non è richiesta alcuna interazione da parte del cliente né la presentazione della pagina di pagamento.
Conclusione del pagamento

Una volta inviata la richiesta di pagamento Next verso i servizi Fabrick il sistema comunica immediatamente l'esito del pagamento, in alternativa è anche possibile utilizzare l'API payment/detail per interrogare la transazione Per completare correttamente il flusso di incasso della ricorrenzaNext, è necessario:
- Verificare l’assenza di richiesta di SCA, in quanto le transazioni Next sono eseguite in assenza del cliente;
- Verificare l’esito della risposta restituita da Fabrick, assicurandosi che la transazione sia stata processata con successo;
- Gestire correttamente il token, garantendo la continuità della catena di pagamenti ricorrenti.
note
Su questa pagina puoi trovare maggiori sulla gestione del token

Oggetto	Campo	Descrizione
`transDetails`	`type`	Valorizzare con `01N` / `03N`
`transDetails.previousTransDetails`	`paymentID`	Identificativo della transazione First (CIT)

Oggetto	Campo	Descrizione
`paymentTypeDetails.creditcard`	`token`	Token della carta utilizzata durante la transazione First

Integrazione

API Only - Non programmate - Con token#

Per effettuare un pagamento ricorrente utilizzando le API Only, segui i passaggi riportati di seguito

Creazione della richiesta di pagamento

Utilizza la chiamata payment/create lato server per creare la richiesta di pagamento. Questo approccio garantisce la sicurezza nella generazione del payload della richiesta e nell'utilizzo della API key.

Imposta il parametro type con 03N per indicare al sistema che si tratta di una transazione Next e utilizza il PaymentID generato dalla transazione First.

Prerequisito: Transazione iniziale di tipo First (03F) completata con successo.

In risposta a questa chiamata otterrai due valori: paymentToken e paymentID

Questi valori servono per:

effettuare la chiamata payment/submit lato server per avviare il pagamento
(opzionale) utilizzare payment/detail per verificare l’esito del pagamento e recuperare le informazioni relative al token.

`POST payment/create` – Next 03N

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-C03N_OrderID",
    "transDetails": {
        "type": "03N",
        "previousTransDetails": {
            "paymentID": "1360119538182"
        }
    }
}

Response

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

Invio dei dati di pagamento

Dopo aver ottenuto paymentToken e paymentID, utilizza la chiamata payment/submit lato server per inviare il token della carta a Fabrick. Assicurati di valorizzare il campo paymentTypeDetails > creditcard > token con il token della carta generato o utilizzato durante la transazione iniziale First (03F).

`POST payment/submit` – Next 03N

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",
    "shopTransactionID": "FBK-S03N_OrderID",
    "paymentTypeDetails": {
        "creditcard": {
            "token": "40ZUU8NXALR33101"
        }
    }
}

A seguito della chiamata payment/submit, possono verificarsi tre scenari principali:

La transazione è stata processata correttamente

L’esito del pagamento 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": "569",
        "shopTransactionID": "FBK-C03N_OrderID",
        "shopTransactionID_2": "",
        "authorizationCode": "188190",
        "paymentID": "1360119538182",
        "currency": "EUR",
        "country": "ITALIA",
        "company": "VISA",
        "tdLevel": "",
        "buyer": {
            "name": "",
            "email": ""
        },
        "risk": {
            "riskResponseCode": "",
            "riskResponseDescription": ""
        },
        "customInfo": {},
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "Y",
        "maskedPAN": "",
        "paymentMethod": "",
        "productType": "Credit",
        "token": "",
        "tokenExpiryMonth": "",
        "tokenExpiryYear": "",
        "userRedirect": {
            "href": "https://sandbox.gestpay.net/pagam/AxerveThankYou.aspx"
        }
    }
}

La banca richiede una nuova autenticazione del titolare carta

Il campo transactionErrorCode restituisce il valore 8026
È necessario contattare il cliente l’utente e inizializzare una nuova transazione First, al fine di ottenere un nuovo identificativo (paymentID) da utilizzare per le future transazioni Next.

Response (richiesta SCA – codice 8026)

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "submit",
        "transactionResult": "KO",
        "transactionErrorCode": "8026",
        "transactionErrorDescription": "Soft decline - Cardholder authentication required",
        "bankTransactionID": "569",
        "shopTransactionID": "FBK-C03N_OrderID",
        "shopTransactionID_2": "",
        "authorizationCode": "",
        "paymentID": "1360119538182",
        "currency": "EUR",
        "country": "ITALIA",
        "company": "VISA",
        "tdLevel": "",
        "buyer": {
            "name": "",
            "email": ""
        },
        "risk": {
            "riskResponseCode": "",
            "riskResponseDescription": ""
        },
        "customInfo": {},
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "Y",
        "maskedPAN": "",
        "paymentMethod": "",
        "productType": "Credit",
        "token": "",
        "tokenExpiryMonth": "",
        "tokenExpiryYear": "",
        "userRedirect": {
            "href": "https://sandbox.gestpay.net/pagam/AxerveThankYou.aspx"
        }
    }
}

Errore durante la richiesta
- La risposta contiene l’oggetto error con:
  - error.code: codice dell’errore
  - error.description: descrizione dell’errore
- Consulta la lista completa degli errori
Response
```
{
    "error": {
        "code": "1165",
        "description": "Token not found"
    },
    "payload": {}
}
```

Verifica e completamento del pagamento

Una volta inviata la richiesta di pagamento Next ai servizi Fabrick, il sistema restituisce immediatamente l’esito della transazione. Contestualmente, viene inviata una notifica S2S contenente l’esito del pagamento insieme ai dati paymentToken e paymentID. Inoltre, è possibile, opzionalmente, utilizzare l’API payment/detail per interrogare la transazione, verificare l’esito del pagamento e ottenere le informazioni relative al token.

Esempio di URL di redirect e notifica S2S:

https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1541109548247&paymentToken=8a901523-67a5-4aca-bbd2-c7c412934289

Confermato l'esito positivo del pagamento è possibile procedere con la cattura o lo storno della transazione e la gestione del token.

`GET payment/detail` – Esito pagamento + informazioni token

Request

GET /api/v1/payment/detail/1360119538182 (PaymentID)
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey **************** (or) PaymentToken: 8a901523-67a5-4aca-bbd2-c7c412934289
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": "569",
        "shopTransactionID": " FBK-C03N_OrderID",
        "shopTransactionID_2": "",
        "authorizationCode": "188190",
        "paymentID": "1360119538182",
        "currency": "EUR",
        "country": "ITALIA",
        "company": "VISA",
        "tdLevel": "FULL",
        "threeDS": {
            "authenticationResult": {
                "authenticationLevel": "2C",
                "authenticationStatus": "Y",
                "authStatusReason": "",
                "challengeResultTransStatus": "",
                "XID": "12e6e4ce-8ccc-49f9-b5a4-18b486f1d29d",
                "AV": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
                "ECI": "05",
                "AVAlgorithm": "",
                "threeDsVersion": "2.1.0"
            },
            "transDetails": {
                "authData": "",
                "authMethod": "02",
                "authTimeStamp": "202407111313",
                "acsID": "48a413bf-fe27-4de2-a39e-dc6039e4aef7"
            }
        },
        "events": [
            {
                "event": {
                    "eventtype": "AUT",
                    "eventamount": "0.00",
                    "eventdate": "11/07/24 13:13:56",
                    "eventARN": "",
                    "eventID": "",
                    "eventReferred": ""
                }
            }
        ],
        "buyer": {
            "name": "",
            "email": ""
        },
        "risk": {
            "riskResponseCode": "",
            "riskResponseDescription": ""
        },
        "customInfo": null,
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "TRUE",
        "dcc": null,
        "maskedPAN": "",
        "paymentMethod": "VISA",
        "productType": "Credit",
        "tokenDetails": {
            "TokenValue": "40ZUU8NXALR33101",
            "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": "05/08/24 00:00:00",
            "amount": "0"
        }
    }
}

Linee guida per l'integrazione​

Transazioni ricorrenti​

Transazioni non programmate​

Flusso First (CIT)​

Impostazione della tipologia di transazione​

Transazioni di Tipo First​

Gestione dell’importo iniziale​

Gestione dei dati della carta e del token​

Con token​

Senza token​

Gestione dell’autenticazione​

Modalità di gestione dell’autenticazione​

Conclusione del pagamento​

Transazioni con importo pari a 0,00 € (ASI)​

Transazioni con importo maggiore di zero e shopLogin con MOTO separato​

Integrazione​

Pagina di pagamento - Non programmate - Senza token#

Creazione della richiesta di pagamento​

POST payment/create – First 03F​

Presentazione della pagina di pagamento​

Integrazione Lightbox o Web Components​

Integrazione Pay By Link​

Verifica e completamento del pagamento​

GET payment/detail – Esito pagamento + informazioni token​

Flusso Next (MIT)​

Impostazione della tipologia di transazione​

Transazioni di tipo Next​

Campi richiesti per l’invio del token nella payment/submit​

Gestione della transazione​

Conclusione del pagamento​

Integrazione​

API Only - Non programmate - Con token#

Creazione della richiesta di pagamento​

POST payment/create – Next 03N​

Invio dei dati di pagamento​

POST payment/submit – Next 03N​

La transazione è stata processata correttamente​

La banca richiede una nuova autenticazione del titolare carta​

Errore durante la richiesta​

Verifica e completamento del pagamento​

GET payment/detail – Esito pagamento + informazioni token​

Linee guida per l'integrazione

Transazioni ricorrenti

Transazioni non programmate

Flusso First (CIT)

Impostazione della tipologia di transazione

Transazioni di Tipo First

Gestione dell’importo iniziale

Gestione dei dati della carta e del token

Con token

Senza token

Gestione dell’autenticazione

Modalità di gestione dell’autenticazione

Conclusione del pagamento

Transazioni con importo pari a 0,00 € (ASI)

Transazioni con importo maggiore di zero e shopLogin con MOTO separato

Integrazione

Creazione della richiesta di pagamento

`POST payment/create` – First 03F

Presentazione della pagina di pagamento

Integrazione Lightbox o Web Components

Integrazione Pay By Link

Verifica e completamento del pagamento

`GET payment/detail` – Esito pagamento + informazioni token

Flusso Next (MIT)

Impostazione della tipologia di transazione

Transazioni di tipo Next

Campi richiesti per l’invio del token nella `payment/submit`

Gestione della transazione

Conclusione del pagamento

Integrazione

Creazione della richiesta di pagamento

`POST payment/create` – Next 03N

Invio dei dati di pagamento

`POST payment/submit` – Next 03N

La transazione è stata processata correttamente

La banca richiede una nuova autenticazione del titolare carta

Errore durante la richiesta

Verifica e completamento del pagamento

`GET payment/detail` – Esito pagamento + informazioni token