Modalità di integrazione > XPay Build > Versione 3

Versione 3

Creazione form di pagamento

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

Per richiamare la versione 3 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:

                                    {
    "sessionId": "Md6fiNaHuADc%2FL%2BcxXVvvw%3D%3D",
    "securityToken": "fd68b72f1fe9471a96865e70a245edd6",
    "fields": [
        {
            "type": "ACTION",
            "id": "SATISPAY",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=SATISPAY...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "MULTIBANCO",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=MULTIBANCO...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "WECHAT",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=WECHAT...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "EPS",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=EPS...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "IDEAL",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=IDEAL...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "PAYPAL",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=PAYPAL...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "P24",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=P24...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "ALIPAY",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=ALIPAY...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "PIS",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=PIS...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "BANCONTACT",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=BANCONTACT...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "GIROPAY",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=GIROPAY...",
            "class": "APM"
        },
        {
            "type": "ACTION",
            "id": "PAY_WITH_CARD",
            "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=PAY_WITH_CARD...",
            "class": "CARD"
        }
    ]
}
                                

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.

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

                                    {
  "sessionId": "%2B33rcw1A7gdFcjYlvfcznA%3D%3D",
  "fields": [
    {
      "type": "TEXT",
      "id": "CARD_NUMBER",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=CARD_NUMBER...",
      "class": "CARD_FIELD"
    },
    {
      "type": "TEXT",
      "id": "EXPIRATION_DATE",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=EXPIRATION_DATE...",
      "class": "CARD_FIELD"
    },
    {
      "type": "TEXT",
      "id": "SECURITY_CODE",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=SECURITY_CODE...",
      "class": "CARD_FIELD"
    },
    {
      "type": "TEXT",
      "id": "CARDHOLDER_NAME",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=CARDHOLDER_NAME...",
      "class": "CARD_FIELD"
    },
    {
      "type": "TEXT",
      "id": "CARDHOLDER_SURNAME",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=CARDHOLDER_SURNAME...",
      "class": "CARD_FIELD"
    },
    {
      "type": "TEXT",
      "id": "CARDHOLDER_EMAIL",
      "src": "https://ngwecomm-dev.nexi.it/phoenix-0.0/hostedfields-demo/iframe.html?id=CARDHOLDER_EMAIL...",
      "class": "CARD_FIELD"
    }
  ]
}
                                

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:

                                    <script type="text/javascript" src="{nexiDomain}/monetaweb/resources/hfsdk.js"></script>
                                

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

                                    <script type="text/javascript">
    let build = new Build({
        onBuildSuccess: function(evtData) {

            // inserire il codice per gestire l'inserimento dei dati avvenuto con successo nel campo specificato: evtData.id
        },

        onBuildError: function(evtData) {

            // inserire il codice per gestire l'inserimento errato dei dati nel campo specificato: evtData.id
            // l'azione può essere gestita in base al codice di errore fornito disponibile in evtData.errorCode
            // i casi possibili sono:
            // HF0001 - generic build field error
            // HF0002 - temporary unavailability of the service
            // HF0003 - session expired – l'esperienza di pagamento deve essere riavviata dalla post orders/build
            // HF0004 - card validation error – il controllo della chiave luhn sul numero della carta è fallito
            // HF0005 - brand not found – il brand della carta non è nella lista dei brand supportati
            // HF0006 - expiration date exceeded  – la carta fornita è scaduta
            // HF0007 – internal error – se il problema persiste il pagamento deve essere riavviato
            // HF0009 – 3DS GDI verification failed – l'esperienza di pagamento deve essere interrotta con un fallimento.
        },
        onConfirmError: function(evtData) {
            // questo evento viene restituito come conseguenza dell'invocazione della funzione SDK confirmData().
            // i casi possibili sono:
            // HF0002 – temporary unavailability of the service
            // HF0003 - session expired – l'esperienza di pagamento deve essere riavviata dalla post orders/build
            // HF0007 – internal error – se il problema persiste il pagamento deve essere riavviato
        },
        onBuildFlowStateChange: function(evtData, state) {
            // questo evento viene restituito per ogni transizione di stato. i valori possibile sono READY_FOR_PAYMENT e PAYMENT_COMPLETE,
			// descritti nei paragrafi successivi.
        },
        cssLink: "https://{tuoDominio}/il_tuo_file_css.css"
           // vedere il paragrafo Modifiche grafiche form raccolta dati carta (CSS)
    });
</script>
                                

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

                                    <input type="button" onClick="build.confirmData(myLoader)">
<script> function myLoader() {<<do un'animazione e rendi il pulsante insensibile>>} </script>
                                

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:

POST /build/finalize_payment

La risposta all'API sopra riportata varia in base alle casistiche di seguito riportate:

Autenticazione 3D Secure: il pagamento richiede l'autenticazione 3D Secure da parte del titolare carta. Vengono restituiti i parametri:

"url": è necessario reindirizzare il cliente verso l'indirizzo contenuto nel campo, dove il titolare carta ha la possibilità di eseguire l'autenticazione ed autorizzare il pagamento. Al termine dell'autenticazione l'esito del pagamento viene restituito verso i parametri di avvio "resultUrl", "notificationUrl" ed eventualmente "cancelUrl".
"state": valorizzato con REDIRECTED_TO_EXTERNAL_DOMAIN".

Esito pagamento: la transazione non richiede autenticazione 3D Secure da parte del titolare carta, il pagamento viene quindi eseguito. Vengono restituiti i parametri:

"operation": oggetto contenente il dettaglio dell'operazione.
"state": valorizzato con "PAYMENT_COMPLETE".

Modifiche grafiche form raccolta dati carta (CSS)

È possibile modificare il form di raccolta dati carta inserendo il link ad un file CSS. Il file deve includere la specifica dello stile da applicare a tutti i tag di input contenuti nelle pagine degli iframe. Inoltre, è possibile differenziare lo stile per ciascuno dei campi della pagina di raccolta dati della carta. Di seguito un esempio:

                                    input {
    display: block;
    width: 100%;
    line-height: 1.5;
    padding: 8px 10px;
    height: 50px;
    background-color: transparent;
    border: 1px solid rgba(50, 50, 50, 0.5);
    border-radius: 2px;
    transition: all 0.2s ease-in-out;
    font-family: Karbon !important;
    font-size: 16px;
    letter-spacing: 0.8px;
    font-weight: normal;
}
#CARD_NUMBER {
    border-color: rgba(45, 50, 170, 0.5);
}
#EXPIRATION_DATE {
    border-color: rgba(45, 50, 170, 0.5);
}
#SECURITY_CODE {
    border-color: rgba(45, 50, 170, 0.5);
}
#CARDHOLDER_NAME {
    border-color: rgba(45, 50, 170, 0.5);
}
#CARDHOLDER_EMAIL {
    border-color: rgba(45, 50, 170, 0.5);
}
                                

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

                                    {
     "sessionId": "%2B33rcw1A7gdFcjYlvfcznA%3D%3D"
     "url": "https://externaldomain...",
}
                                

API Aggiuntive

Annullo sessione: POST /build/cancel
Interrogazione stato sessione: GET /build/state
Interrogazione dati carta: GET /build/cardData
Controllo integrità: GET /build/integrity

NOTA:

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