XPay Build
XPay Build is an approach that allows merchants to host the payment form within their own ecommerce, at the same time avoiding having to manage card data: the fields where this information is entered are contained in iframes connected to the XPay server, guaranteeing the security of card data and at the same time improving the shopping experience.
With XPay Build, pre-built HTML user interface components are available, such as input fields for collecting user information and buttons for alternative payment methods enabled on the merchant's terminal, such as ApplePay, Paypal, etc.
Payment form creation
The card data collection form as well as the alternative payment methods (APM) buttons are returned by the 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.
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 | |||||||||||||||||||||||||||||||||||||
|
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:
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 | ||||||||||||||||||||||
|
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".
Session cancellation
Cancel a payment session XPay Build.
Once a session is invalidated, any further submissions of requests related to the canceled session are destined to fail. Therefore, it will be necessary to invoke the API POST /orders/build for the generation of a new sessionId.
This API can be applied to a payment cancellation button placed in the merchant's checkout: it is not mandatory to implement the API; in case it is not used, any session will be invalidated upon session expiration (5 minutes).