No results

Version 3

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

    POST /build/finalize_payment

The response to the above API changes according to the following cases:

  • 3D Secure authentication: payment requires 3D Secure authentication by the cardholder. Parameters are returned:
    • "url": the customer must be redirected to the address contained in the field, where the cardholder can authenticate and authorize the payment. At the end of the authentication, the payment result is returned to the request parameters "resultUrl", "notificationUrl" and possibly "cancelUrl".
    • "state": set with REDIRECTED_TO_EXTERNAL_DOMAIN".
  • Payment result: the transaction does not require 3D Secure authentication by the cardholder, the payment is then completed. Parameters are returned:
    • "operation": object containing the detail of the operation.
    • "state": set with "PAYMENT_COMPLETE".

Graphic Changes to Credit Card Data Collection Form (CSS)

You can modify the credit card data collection form by inserting a link to a CSS file. The file should include the style specification to be applied to all input tags contained in the iframe pages. Additionally, you can differentiate the style for each of the fields on the credit card data collection page. Below is an example:

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.