> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Process

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

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant MF as Merchant Frontend
    participant MS as Merchant Server
    participant XS as xPay Server
    participant XC as xPay Checkout

    rect transparent
    note over MS,XS: Create a customer first
    MS->>XS: POST /customers/create { email, ... }
    XS-->>MS: { customerId }
    end

    rect transparent
    note over MS,XS: Initialize setup method
    alt Hosted Flow
        MS->>XS: POST /setup-method/create { customerId, callbackUrl, ... }
    else Server Side Flow
        MS->>XS: POST /setup-method/s2s/create { cardDetails, customerId, ... }
    end
    XS-->>MS: { setupMethodId, fwdUrl }
    end

    rect transparent
    note over MS,MF: Forward data to browser
    MS-->>MF: Send fwdUrl and setupMethodId
    end

    rect transparent
    note over MF,XC: Open xPay checkout
    MF->>XC: Open fwdUrl
    end

    rect transparent
    note over XC,XS: Customer completes setup
    XS->>MS: Webhook setup_method.success { setupMethodId, pmId }
    XS-->>MF: Redirect to callbackUrl
    end

    rect transparent
    note over MS,XS: Charge tokenized payment method (later)
    MS->>XS: POST /charge-tokenised-pm { pmId, customerId, amount, ... }
    XS-->>MS: { paymentResult }
    end
```

<Steps>
  <Step title="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](/developer-resources/endpoints/customer/create-customer) for details.

    <Note>
      The `customerId` is required for creating a setup method and charging the payment method later.
    </Note>
  </Step>

  <Step title="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](/developer-resources/endpoints/setup-method/create-setup-method) 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](/developer-resources/endpoints/setup-method/create-s2s-setup-method) for details.

    Both return a `setupMethodId` and `fwdUrl` in the response.

    <Note>
      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.
    </Note>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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.
    <Tip>The Merchant Server should log or store this identifier for future reference.</Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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 JavaScript theme={null}
    const redirectToSetup = () => {
        const url = new URL(fwdUrl); // fwdUrl received from your server after creating a setup method
        window.open(url.href).focus();
    };
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/developer-resources/endpoints/setup-method/charge-tokenised-pm) for details.

    ```javascript JavaScript theme={null}
    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();
    };
    ```
  </Step>

  <Step title="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](/developer-resources/endpoints/setup-method/get-setup-method) for details.

    ```javascript JavaScript theme={null}
    const getSetupMethodStatus = async (setupMethodId) => {
        const response = await fetch(`/setup-method/${setupMethodId}`);
        return await response.json();
    };
    ```
  </Step>

  <Step title="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](/developer-resources/endpoints/setup-method/get-payment-method-token) 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 JavaScript theme={null}
    const getPaymentMethodTokenStatus = async (paymentMethodTokenId) => {
        const response = await fetch(`/payment-method-token/${paymentMethodTokenId}`);
        return await response.json();
    };
    ```

    <Note>
      It's recommended to check the token status before attempting to charge a payment method to ensure it's still valid.
    </Note>
  </Step>
</Steps>

***

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.