Integration Process

Learn how to integrate xPay’s Setup Method flow to securely store and charge customer payment methods.

1. Create Customer (Merchant Server → xPay Server)

   Before setting up a payment method, you need to create a customer in the xPay system. Make a create-customer POST request to xPay’s API from the Merchant Server, which returns a customerId in the response. See create-customer API for details.

   The customerId is required for creating a setup method and charging the payment method later.

2. Create Setup Method (Merchant Server → xPay Server)

   Initialize the setup method using one of the following options:

   • Hosted Flow — Make a create-setup-method POST request. xPay handles the payment form UI. See create-setup-method API for details.
   • Server Side Flow — Make a create-s2s-setup-method POST request with the customer’s card details directly from your server. See create-s2s-setup-method API for details.

   Both return a setupMethodId and fwdUrl in the response.

   The callbackUrl in the request should be configured to your client-side page responsible for managing the redirect from xPay checkout following the setup process.

   The Server Side flow requires PCI DSS compliance, as it involves handling raw card data on your server. Server Side currently only supports raw card payments.

3. Receive Setup Method Confirmation (xPay Server → Merchant Server)

   Once the setup method is created, the xPay Server will respond with a setupMethodId, which is used to track the setup status throughout the process.

4. Forward Setup Method data to Merchant Frontend (Merchant Server → Merchant Frontend)

   The Merchant Server forwards the setup method data with fwdUrl to the Merchant Frontend, enabling it to manage user interactions related to the payment method setup.

5. Redirect to xPay Checkout (Merchant Frontend → xPay Client)

   Redirect the user to xPay’s checkout page to initiate the payment method setup using the fwdUrl.

   JavaScript

   const redirectToSetup = () => {
       const url = new URL(fwdUrl); // fwdUrl received from your server after creating a setup method
       window.open(url.href).focus();
   };
   
6. Handle Setup Method Webhook (xPay Server → Merchant Server)

   • Configure your webhook endpoint to receive the setup_method.success event.
   • When the setup is successful, you’ll receive a webhook with the pmId (Payment Method ID).
   • Store this pmId securely in your database for future use.
7. Charge Tokenized Payment Method (Merchant Server → xPay Server)

   Once you have the pmId, you can charge the customer’s payment method using the charge-tokenised-pm POST request. See charge-tokenised-pm API for details.

   JavaScript

   const chargePaymentMethod = async (pmId, customerId, amount, currency) => {
       const response = await fetch('/payments/charge-tokenised-pm', {
           method: 'POST',
           headers: {
               'Content-Type': 'application/json'
           },
           body: JSON.stringify({
               pmId,
               customerId,
               amount,
               currency
           })
       });
       return await response.json();
   };
   
8. Monitor Setup Method Status (Optional)

   You can monitor the status of the setup method using the get-setup-method GET request. See get-setup-method API for details.

   JavaScript

   const getSetupMethodStatus = async (setupMethodId) => {
       const response = await fetch(`/setup-method/${setupMethodId}`);
       return await response.json();
   };
   
9. Track Payment Method Token Status (Optional)

   You can track the status of a payment method token using the get-payment-method-token GET request. See get-payment-method-token API for details.

   The payment method token can have two statuses:

   • LIVE: The token is active and can be used for transactions
   • DELETED: The token has been deleted and cannot be used for transactions

   JavaScript

   const getPaymentMethodTokenStatus = async (paymentMethodTokenId) => {
       const response = await fetch(`/payment-method-token/${paymentMethodTokenId}`);
       return await response.json();
   };
   

   It’s recommended to check the token status before attempting to charge a payment method to ensure it’s still valid.

---

By following this process, you can securely store customer payment methods and charge them for future transactions. The setup method flow provides a seamless experience for customers while maintaining security and compliance standards.