XPay Fusion

XPay Fusion is a PCI DSS-compliant payment solution to collect payments from your customers on your webapp without them having to redirect to a third-party payment page.

Integrating XPay Fusion

XPay e2e Integration - Sequence Diagram

To integrate XPay Fusion with your eCommerce store, you need to:

• Integrate Fusion APIs on the server side and
• Add the Fusion embedded element on the client side by using XPay JS SDK.

Step by step flow

• When your customer comes to the checkout page, they enter their card details into the card details form rendered in a secure iframe, enabled by the Fusion Embedded Element. They then click the Place Order button.
• The Fusion Embedded Element can be added to your frontend project as follows:

npm i @xstak/xpay-element

3. Import the XPay provider and add the required keys

import { XPay } from '@xstak/xpay-element';
function XPayPayment() {
return  (
<XPay xpay={{ publishableKey: "", accountId: "", hmacSecret: ""}}>
<Payment />
</XPay>
)}

4. Render the Fusion Embedded Element

import React, { useState } from 'react';
import { PaymentElement, useXpay } from '@xstak/xpay-element';
export const Payment = () => {
    const options = {
        override: true,
        fields: {
          creditCard: {
            placeholder: "4234 1234 1234 1234",
            label: "Enter your credit card",
          },
          exp: {
            placeholder: "Exp. Date",
          },
        },
        style: {
          ".input": {
            "border": "1px solid black",
            "border-radius": "15px"
           },
          ".invalid": {},
          ".label": {
            "font-size": "18px"
           },
          ":focus": {},
          ":hover": {},
          "::placeholder": {},
          "::selection": {},
        },
      };
    const xpay = useXpay();
    const pay = async() => { 
const { message, error } = await xpay.confirmPayment("card", payment_intent_client_secret, customer = {name: ‘Dane Joe}, encryptionKey);
//if payment is successful, request backend to create order.
//else if payment is unsuccessful, show error message
    }
    return(
        <>
        <PaymentElement options={options} onReady={(event) => {
            console.log("ready event", event);
          }} />
        <Button type="primary" onClick={pay}>
          Pay Now
        </Button>
    )
}

Important: XPay SDK supports custom styling and changing labels and placeholder texts of input fields as per your design to provide a seamless experience to your customers.

5. When the customer clicks on the Place Order button, the frontend requests the backend to start the payment processing by passing relevant details about the cart (cart id, cart total etc) and the customer (customer name and contact details etc). Since the order would not have been created as yet, it is recommended that the cart id be used at this step.

6. The backend receives this request from the frontend and creates a payment intent by calling the Create Payment Intent API and returns the response to the frontend:

a. The cart id should be added in the metadata object, with the key of order_reference, of Create Payment Intent call payload to reference it later. However, any other key/value can also be added in the metadata object.

b. Important: Payment Intent id is the single source of truth in XPay Fusion and it will be used as a reference for the payment and any possible future actions such as refund, etc.

curl --location 'https://xstak-pay-stg.xstak.com/public/v1/payment/intent' \
--header 'x-api-key: {{x-api-key}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{x-signature}}' \
--header 'Content-Type: application/json' \
--data '{
   "amount": 10,
   "currency": "PKR",
   "payment_method_types": "card",
   "customer": {
       "name": "",
       "email": "",
       "phone": ""
   },
   "metadata":{
       "order_reference":""
   },
   "gateway_instance_id": "" // get from gateways in the settings
}'

c. Payment intent client secret and encryptionKey are included in the response of the Create Payment Intent call. This client secret and encryptionKey will be needed to capture the payment and pass in confirmPayment SDK method as shown below.

7. Once the frontend receives the payment intent from the backend, it will call the confirmPayment method of the XPay JS SDK and pass it the payment intent client secret.

const { message, error } = await xpay.confirmPayment("card", payment_intent_client_secret, customer = {name: ‘Dane Joe}, encryptionKey);

8. This confirmPayment SDK method will return a promise which will be resolved with a response object citing either success or failure message with the reason.

a. If successful, the frontend can request the backend to create the order. It is recommended that the backend retrieve the payment intent from XPay by calling the Retrieve Payment Intent API, verify the payment information and then create the order and inform the frontend.

b. If unsuccessful, the frontend should show an error message to the customer.

c. You can also set up webhooks to get notified of payment status asynchronously.

Form Validation Error Handling

We have an event named ready which will return true if all fields have been filled by user and form is ready to be submitted.

It will ensure that the website only enables the payment button if all required data has been added to the iframe form.

<code class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; >xpay.on(&#x27;ready&#x27;, callbackFunction);</code>