No results

Version 1

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

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.

WARNING: for the proper functioning of XPay Build solution, it is necessary for the browser used to allow the use of third-party cookies.

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:

The individual iframes must be shown to the customer: once the fields are filled in, an event is returned with an object composed as follows:

  • "event": set with "BUILD_FLOW_STATE_CHANGE".
  • "state": set with "READY_FOR_PAYMENT"

The event confirms the possibility to proceed with the payment by calling 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".

Error handling

The credit card data collection form may return errors via an event, such as incorrect data entered in iframes or session expiration. Below is the detail of the object:

NAME DESCRIPTION FORMAT
event Valued with "BUILD_ERROR". AN
id Identifier of the field referenced by the event. AN
errorCode Error code. Possible values:
  • HF0001: Validation error
  • HF0003: Session expired
 AN
errorMessage Error message. Possible values:
  • Validation error: incorrect or missing data entered.
  • Session expired: XPay Build session timed out.
 AN

Payment via APM

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

  • "state": set with "REDIRECTED_TO_EXTERNAL_DOMAIN".
  • "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.