BUILD Functionality

Overview

The BUILD functionality allows E-commerce merchants to expose the payment functionalities through a user experience. It is well-aligned with the ecommerce platform style guides without being forced to perform any PCI-DSS certification of their own infrastructure.

This result is obtained through the integration in their HTML pages of a series of iframe tags, each of them pointing to a single-field html page hosted by the PCI-DSS compliant Nexi infrastructure.

Payment Use Case

The payment flow has to be initiated through a server to server call:

POST https://<nexi domain>/api/orders/build

In case of success, the service will return a JSON module that contains a set of fields to be translated in HTML code by the ecommerce platform developers.

Each of the returned field is designed to provide a specific functionality like collecting a PCI sensitive data, downloading a terms&conditions document, performing an action.

The approach is based on very little set of controls and, at the same time, it provides a very high level of flexibility in managing very different workflows imposed by the several payment methods available on the market.

Payment Initiation with Payment Method Selection

The following diagram shows the sequence of the operations during a regular payment. In this case, the returned field set is paymentMethodSelection.

Once the HTML fields are loaded on the browser, the user can select one of the proposed payment methods.

Based on the selection, the invoked service may return one of three alternative options:

• paymentStatus
• fieldSet
• redirectUrl

These are described in the Payment Initiation Flow.

Payment Initiation with Card

The following diagram shows the sequence of the operations during the payment forced to start with cards only. In this case, the returned field set is cardDataCollection.

Once the HTML fields and HTML pages nested in the iframes are loaded on the browser, the user can start to enter the card data.

After having entered all the data, the user can proceed with the payButton to confirm the payment.

The entered data is then used to initiate the payment through the authorization gateway.

Based on the selection, the invoked service may return one of three alternative options:

• paymentStatus
• fieldSet
• redirectUrl

These are described in the Payment Initiation Flow.

Payment Initiation Flow

The payment initiation flow can further be split in three different flows as described below:

1. paymentStatus

the payment was completed in a synchronous way, either for a failure or for a frictionless response of 3DS verification.

In either cases, the payment result is provided in response to the caller and, after having forwarded the payment status to the ecomm platform BE, the payment flow can be considered as completed.

2. fieldSet

The payment is expected to continue with a further intermediate view to be populated with the provided field-set.

In this case it is required to act as per the initial field-set returned by the POST /orders/build web service.

3. redirectUrl

The payment is expected to continue on an external domain.

Usually this event happens when the user has to perform a strong customer authentication requested by the issuer of the payment instrument (i.e. 3DS verification, Bank account SCA, APM authentication).

In this case it is required to navigate to the provided URL and wait to receive back the control on the originally provided resultUrl or cancelUrl, after the authentication was performed or cancelled.

Field Types

The field types (action, text, and anchor) are descritbed in this section.

1. action

The payment method field is represented by the following JSON module:

{ 
    "type":"action", 
    "class":"cardPaymentMethod", 
    "id":"card",

The params of the JSON indicate:

• "class": provides additional info to support the visual-grouping of the objects in the page and allows differenciating the css style. The possible values are:
  • "cardPaymentMethod": payment with cards.
  • "accountPaymentMethod": payment with bank account.
  • "walletPaymentMethod": payment based on cards accessible through wallet credentials.
  • "bnplPaymentMethod": buy-now-pay-later payment method.
  • "apmPaymentMethod": any other alternative payment method.
• “actionButton”: a button to perfom an action.
• “cancelButton”: a button to cancel the current operation.
• "id": it is the unique identifier of the action, defined by nexi.
• "src": it is the url to be loaded in the HTML iframe.

The ecomm platform developer is responsible to generate the corresponding HTML code to be embedded in the payment page as an HTML iframe, like the following example:

<iframe id="card" width="300" height="200"
    src="https://<fedomain>/card?sid=hljkhjl..."/>

The iframe will then be loaded with an HTML page hosted by Nexi infrastructure. The HTML page will contain a clickable icon related to the payment pethod or action realized with the button HTML tag. The ecomm platform developer is expected to provide a customized CSS specification for the above defined classes.

2. text

The field is represented by the following JSON module:

{
    "type":"text",
    "class":"cardData",
    "id":"cardNumber",

The ecomm platform developer is responsible to generate the corresponding HTML code to be embedded in the payment page, as follows:

<iframe id="cardNumber"
    width="300"
    height="200"
    src="https://<fedomain>/cardnumber?sessionId=hljkhjl...">

The iframe will then be loaded with an HTML page hosted by Nexi's infrastructure. The HTML page, provided by Nexi at the agreed URL, will contain an input tag of class cardData for which the ecomm platform developer is expected to provide a customized CSS specification.

HTML loaded in the iFrame may look as follows:

<!DOCTYPE html>
  <html>
    <body>
      <input class="cardData" type="text">

3. anchor

The field is represented by the following JSON module:

{
    "type":"anchor",
    "id":"privacyConditions",
    "href"="https://<fedomain>/f6b79e75-9bbb-43e3-8617-5f1ca6b81990"

The ecomm platform developer is responsible to generate the corresponding HTML code to be embedded in the payment page, as follows:

<a href=" https://<fedomain>/f6b79e75-9bbb-43e3-8617-5f1ca6b81990" download>

  Click to download Privacy conditions

Contents are made available through non-authenticated services.

Field-set Types

This section describes the field-set types.

1. paymentMethodSelection field-set type

This field-set contains a list of the payment methods allowed to the payer.

Each payment method is represented as an action field type.

{
    "fieldSet":"paymentMethodSelection",
    "fields": [
      {

The ecom platform developer has the responsibility to translate the field set into an HTML view respectful of the imposed UI style guidelines.

2. cardDataCollection field-set type

This field-set contains a list of fields to allow the user entering the card data in a PCI-DSS safe way and start a payment.

The page is composed by the following fields:

{
    "fieldSet":"cardDataCollection",
    "fields": [
      {

The above field set is designed to allow the integrator build a fully customized version of the Nexi hosted payment page.

API Authentication

The server to server web services, that is, POST /orders/build, are authenticated by adding a valid API Key in the header of the call, like the following example:

x-api-key: 3f382c7c-e8af-46cd-a191-18dc6991b8a4

Instead, the calls originated by the browser use a dedicated short-term and limited-capabilities authentication tokens that will be generated during the POST /orders/build call.

These tokens can be used as an authorization bearer header in the calls originated by the hosted fields running in the browser app.

The propagation of these tokens along the chain is embedded in the defined architecture and no additional actions are required to the ecomm platform developer with respect to what is already specified in the Field types section.