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)

Start the setup method process by making a create-setup-method POST request to xPay’s API from the Merchant Server, which returns a setupMethodId and fwdUrl in the response. See create-setup-method API for details.
The callbackUrl string in the create-setup-method request should be configured to your client-side page responsible for managing the redirect from xPay checkout following the setup process.
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.
The Merchant Server should log or store this identifier for future reference.
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.