Nessun risultato trovato

Versione 2

Questa versione di XPay Build è dedicata al servizio PagoPa.

Creazione form di pagamento

Il form raccolta dati carta così come i bottoni dei metodi di pagamento alternativi (APM) vengono restituiti dall'API:

POST /orders/build

Per richiamare la versione 2 di XPay Build, è necessario valorizzare nell'API sopra riportata il parametro "version" con "3".

La chiamata restituisce un oggetto, contenente gli iframe corrispondenti al metodo di pagamento tramite carta e agli APM attivi sul terminale dell'esercente. Di seguito un'esempio in formato JSON:

Ogni iframe rappresenta un bottone che permette al cliente di scegliere il metodo di pagamento desiderato, questi componenti devono essere quindi mostrati nella pagina di checkout del negozio.

La gestione del pagamento subisce delle variazione tra carte e APM, di seguito le indicazioni.

Pagamento tramite carta

Una volta cliccato sul metodo di pagamento tramite carta, viene restituito, tramite un evento, un oggetto contenente i seguenti dati:

  • "event": parametro valorizzato con "BUILD_FLOW_STATE_CHANGE".
  • "state": parametro valorizzato con "CARD_DATA_COLLECTION".
  • "fieldSet": oggetto contenente gli iframe dei singoli campi necessari per l'inserimento dei dati carta, di seguito il dettaglio.

OGGETTO FIELDSET

NOME DESCRIZIONE FORMATO
sessionId Identificativo della sessione. AN
fields Array di oggetti contenenti gli iframe dei singoli campi necessari per l'inserimento dei dati carta. Array
type

Tipologia del campo, valori possibili:

  • TEXT: campo di testo che necessita di una compilazione da parte del titolare carta, come i campi per l'inserimento dati carta.
  • ACTION: campo che necessità di un'azione da parte del titolare carta, come le checkbox per accettare i termini e condizioni.
 AN
id

Identificativo del campo, valori possibili:

  • CARD_NUMBER: pan carta.
  • EXPIRATION_DATE: scadenza carta.
  • SECURITY_CODE: codice di sicurezza cvv/cv2 carta.
  • CARDHOLDER_NAME: nome del titolare carta.
  • CARDHOLDER_SURNAME: cognome del titolare carta.
  • CARDHOLDER_EMAIL: mail del titolare carta.
  • PRIVACY_CONDITIONS: eventuali termini e condizioni per procedere con il pagamento.
 AN
src URL iframe. AN
class

Classe del campo, valori possibili:

  • CARD_FIELD
 AN

Di seguito un esempio dell'oggetto in formato JSON dell'oggetto "fieldSet":

Sulla pagina HTML, è necessario inserire dinamicamente ciascun campo dall'array "fields" ricevuto.

ATTENZIONE: È necessario includere, accompagnata da un elemento HTML checkbox, l'informativa sulla privacy di Nexi, disponibile al link https://www.nexi.it/privacy/xpay.html. Si consiglia di incorporare direttamente il link indicato all'interno della pagina in modo che il testo rimanga sempre aggiornato.

Inizializzazione SDK

In base alle azioni del cliente, una volta che uno dei campi carta è stato inserito correttamente, vengono generati diversi eventi sulla pagina HTML principale. Gli eventi permettono di fornire un feedback adeguato al cliente per informarlo sulla correttezza dei dati inseriti. La cattura di tali eventi è resa più semplice grazie ad un SDK fornito da Nexi.

Inserire questa dichiarazione in un punto qualsiasi della pagina, sostituendo "nexiDomain" con il dominio di test o di produzione di XPay:

Successivamente, impostare le azioni da eseguire in ognuna delle seguenti situazioni:

Bottone di conferma dati inseriti

I dati della carta, inseriti dal cliente negli iframe interni, vengono memorizzati sul server Nexi solo nel momento in cui il cliente clicca sul pulsante di conferma. Questo pulsante deve essere sviluppato in autonomia sulla pagina di checkout del sito ecommerce.

Al pulsante deve essere associato un evento "onClick" che richiama la funzione "confirmData":

La funzione "confirmData" può generare i seguenti cambi di stato:

  • PAYMENT_COMPLETE: il pagamento è stato concluso in uno step. Non sono necessarie ulteriori operazioni. Viene restituito l'oggetto "operation" contenente il dettaglio dell'operazione.
  • READY_FOR_PAYMENT: questo evento conferma che è possibile procedere con il pagamento richiamando l'API:

    GET /build/cardData

Con l'API sopra riportata sarà possibile recuperare le informazioni sulla carta inserita dall'utente, con cui PagoPa potrà suggerire la PSP più appropriata per poter procedere con il pagamento.

Conferma del pagamento

Quando l'utente conferma il pagamento con il PSP selezionato, il backend di PagoPA dovrà invocare l'API:

POST /build/confirm_payment

La risposta all'API sopra riportata varia a seconda dei seguenti scenari:

  • Richiesta di verifica GDI: In questo caso, è necessario creare un nuovo layout di pagina HTML con un singolo frame interno per consentire al server 3DS di raccogliere dati sensibili del browser necessari per valutare il rischio della transazione.
    Il sessionId fornito sostituisce quello precedente per eventuali richieste successive GET /build/state. Le informazioni contenute nel campo devono essere utilizzate per determinare il parametro src del frame interno mirato a eseguire la verifica GDI:
    In questo caso, il frame interno può rimanere nascosto poiché la pagina caricata non mostra alcuna informazione.
    L'operazione può richiedere da 2 a 10 secondi, quindi è opportuno mostrare un caricamento per far sapere all'utente che qualcosa sta accadendo in background.
  • Pagamento completato: Questo è il caso in cui l'esperienza di pagamento arriva al completamento durante questa operazione. Nel caso specifico, ciò può verificarsi solo in caso di fallimento del pagamento a causa di un problema tecnico occorso durante questa fase.

Pagamento tramite APM

Una volta cliccato sul metodo di pagamento alternativo, viene restituito, tramite un evento, un oggetto contenente i seguenti dati:

  • "sessionId": valorizzato con l'identificativo della sessione di pagamento.
  • "url": indirizzo necessario per il reindirizzamento verso la pagina di cassa del metodo di pagamento alternativo. Al termine del pagamento l'esito viene restituito verso i parametri di avvio "resultUrl", "notificationUrl" ed eventualmente "cancelUrl".

API Aggiuntive

NOTA:

La soluzione XPay Build non è compatibile con la funzionalità DCC.