Integration Process

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.

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.

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 forwards the setup method data with fwdUrl to the Merchant Frontend, enabling it to manage user interactions related to the payment method setup.

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

const redirectToSetup = () => {
    const url = new URL(fwdUrl); // fwdUrl received from your server after creating a setup method
    window.open(url.href).focus();
};

• 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.

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.

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();
};

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

const getSetupMethodStatus = async (setupMethodId) => {
    const response = await fetch(`/setup-method/${setupMethodId}`);
    return await response.json();
};

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

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