Modalità di integrazione > XPay Build

XPay Build

XPay Build è un approccio che permette all'esercente di ospitare il form di pagamento all'interno del proprio ecommerce, evitando allo stesso tempo di dover gestire i dati carta: i campi dove vengono inserite queste informazioni sono contentuti in degli iframe collegati al server XPay, garantendo la sicurezza dei dati carta e al contempo rendendo migliore l'esperienza di acquisto.

Con XPay Build, sono disponibili componenti dell'interfaccia utente HTML già pronti, come campi di input per la raccolta di informazioni dall'utente e bottoni per i metodi di pagamento alternativi abilitati sul terminale dell'esercente, come ApplePay, Paypal, ecc.

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

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"
    }
  ]
}
                                

I singoli iframe dovranno essere mostrati al cliente: compilati i campi, viene restituito un evento con un oggetto così composto:

"event": valorizzato con "BUILD_FLOW_STATE_CHANGE".
"state": valorizzato con "READY_FOR_PAYMENT"

L'evento conferma la possibilità di 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".

Gestione degli errori

Il form di raccolta dati carta può restituire, tramite evento, degli errori come dati non corretti inseriti negli iframe o scadenze della sessione. Di seguito il dettaglio dell'oggetto:

NOME

DESCRIZIONE

FORMATO

event	Valorizzato con "BUILD_ERROR".	AN
id	Identificativo del campo a cui fa riferimento l'evento.	AN
errorCode	Codice errore. Valori possibili: HF0001: Validation error HF0003: Session expired	AN
errorMessage	Messaggio di errore. Valori possibili: Validation error: dati inseriti non corretti o mancanti. Session expired: sessione XPay Build scaduta.	AN

Pagamento tramite APM

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

"state": valorizzato con "REDIRECTED_TO_EXTERNAL_DOMAIN".
"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".