No results

Version 2

This version of XPay Build is dedicated to the PagoPa service.

Payment form creation

The card data collection form as well as the alternative payment methods (APM) buttons are returned by the API:

POST /orders/build

To invoke version 2 of XPay Build, you need to set the "version" parameter to "3" in the above mentioned API.

The request returns an object containing the iframes corresponding to the card payment method and the APMs active on the merchant's terminal. Below is an example in JSON format:

Each iframe represents a button that allows the customer to choose the desired payment method, these components must then be shown on the shop checkout page.

Payment management is subject to variations between cards and APMs, indications below.

Payment by card

Once the card payment method has been clicked, an object containing the following data is returned via an event:

  • "event": parameter set to "BUILD_FLOW_STATE_CHANGE".
  • "state": parameter set to "CARD_DATA_COLLECTION".
  • "fieldSet": object containing the iframes of the individual fields necessary for entering card data, details below.

FIELDSET OBJECT

NAME DESCRIPTION FORMAT
sessionId Session identifier. Object
fields Array of objects containing the iframes of the individual fields necessary for entering card data. Object
type

Type of field, possible values:

  • TEXT: text field that needs to be filled in by the cardholder, like the fields for entering card data.
  • ACTION: field that requires an action by the cardholder, such as the checkboxes to accept the terms and conditions.
 AN
id

Field identifier, possible values:

  • CARD_NUMBER: pan card.
  • EXPIRATION_DATE: card expiration.
  • SECURITY_CODE: CVV/CV2 card security code.
  • CARDHOLDER_NAME: cardholder name.
  • CARDHOLDER_SURNAME: cardholder surname.
  • CARDHOLDER_EMAIL: cardholder email.
  • PRIVACY_CONDITIONS: any terms and conditions for proceeding with the payment.
 AN
src Iframe URL. AN
class

Field class, possible values:

  • CARD_FIELD
 AN

Below is an example of the object in JSON format of the "fieldSet" object:

On the HTML page, it's necessary to dynamically inject each field from the received 'fields'.

ATTENTION: t is necessary to include, accompanied by a checkbox, the privacy policy of Nexi, available at the link https://www.nexi.it/privacy/xpay.html. It is recommended to directly embed the indicated link within the page so that the text remains always updated.

SDK Initialization

Based on the customer's actions, once one of the card fields has been entered correctly, several events are triggered on the main HTML page. These events allow for providing appropriate feedback to the customer to inform them about the correctness of the entered data. Capturing these events is made easier by an SDK provided by Nexi.

Insert this statement at any point on the page, replacing "nexiDomain" with the test or production domain of XPay:

Afterwards, set up the actions to be performed in each of the following situations:

Confirmation Button for Entered Data

The card data, entered by the customer in the internal iframes, are stored on the Nexi server only when the customer clicks on the confirmation button. This button must be independently developed on the checkout page of the ecommerce site.

The button must have an "onClick" event associated with it that calls the "confirmData" function:

The "confirmData" function can trigger the following state changes:

  • PAYMENT_COMPLETE: Payment has been completed in one step. No further actions are required. The 'operation' object containing the operation details is returned.
  • READY_FOR_PAYMENT: This event confirms that it's possible to proceed with the payment by invoking the API:

    GET /build/cardData

With the above API, it will be possible to retrieve the information about the card entered by the user, with which PagoPa can suggest the most appropriate PSP to proceed with the payment.

Payment Confirmation

When the user confirms the payment with the selected PSP, the backend of PagoPA must invoke the API:

POST /build/confirm_payment

The response to the above API varies depending on the following scenarios:

  • Request for GDI verification: In this case, it is necessary to create a new HTML page layout with a single internal frame to allow the 3DS server to collect browser-sensitive data required to assess the transaction risk.
    The provided sessionId replaces the previous one for any subsequent GET /build/state inquiries. The information contained in the field must be used to determine the src parameter of the internal frame aimed at performing the GDI verification:
    In this case, the internal frame can remain hidden as the loaded page does not show any information.
    The operation can take from 2 to 10 seconds, so it is appropriate to show a loader to let the user know that something is going on in background.
  • Payment complete: This is the case where the payment experience gets to completion during this operation. In the specific case, this can only happen in case of payment failure due to a technical issue occurred during this phase.

Payment via APM

Once the alternative payment method has been clicked, an object containing the following data is returned via an event:

  • "sessionId": filled with the payment session identifier.
  • "url": address required for redirection to the checkout page of the alternative payment method. At the end of the payment, the result is returned to the request parameters "resultUrl", "notificationUrl" and possibly "cancelUrl".

Additional APIs

NOTE:

The XPay Build solution is not compatible with the DCC feature.