> ## 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

> Discover how to integrate xPay’s payment flow into your website using xPay’s payment gateway APIs.

```mermaid theme={null}
sequenceDiagram
  participant MF as Merchant Frontend
  participant MS as Merchant Server
  participant XS as xPay Server
  participant XC as xPay Checkout
  autonumber
  rect transparent
    Note over MF, MS: User clicks "Pay" on Merchant Frontend
    MF ->> MS: Request to create payment
  end
  rect transparent
    Note over MS, XS: Initiate payment intent
    MS ->> XS: POST /create-intent {amount, currency, callbackUrl, ...}
    XS -->> MS: { xIntentId, fwdUrl }
  end
  rect transparent
    Note over MS, MF: Forward intent data
    MS -->> MF: Send fwdUrl and xIntentId
  end
  rect transparent
    Note over MF, XC: Redirect to xPay Checkout
    MF ->> XC: Open fwdUrl
  end
  rect transparent
    Note over XC, XS: User completes checkout
    XS ->> MS: Webhook intent.<success|failed> { xIntentId, ... }
    XS -->> MF: Redirect to callbackUrl?xpay_intent_id
  end
  rect transparent
    Note over MF, MS: Frontend queries status from backend
    MF ->> MS: GET /payment-status?xpay_intent_id
    MS -->> MF: { status: SUCCESS | FAILED }
    MF -->> MF: Display page based on status
  end
```

<Steps>
  <Step title="Initiate Payment Intent (Merchant Server → xPay Server)">
    Start the transaction by making a **create-intent** POST request to xPay's API from the Merchant Server, which returns an `fwdUrl` in the response.
    See [create-intent API](/developer-resources/endpoints/payments/create-intent) for details.

    <Note>
      The **callbackUrl** string in the **create-intent** request should be configured to your client-side page responsible for managing the redirect from xPay checkout following a payment attempt.
    </Note>
  </Step>

  <Step title="Receive Payment Intent Confirmation (xPay Server → Merchant Server)">
    Once the payment intent is created, the xPay Server will respond with an `xIntentId`, which is used to track the payment status throughout the transaction.
    <Tip>The Merchant Server should log or store this identifier for future reference.</Tip>
  </Step>

  <Step title="Forward Intent data to Merchant Frontend (Merchant Server → Merchant Frontend)">
    The Merchant Server forwards the intent data with `fwdUrl` to the Merchant Frontend, enabling it to manage user interactions related to the payment.
    <Info>Ensure the frontend is ready to handle the payment initiation process.</Info>
  </Step>

  <Step title="Redirect to xPay Checkout (Merchant Frontend → xPay Client)">
    Redirect the user to xPay’s checkout page to initiate the payment using the `fwdUrl`.

    ```javascript JavaScript theme={null}
    const redirectToCheckout = () => {
        const url = new URL(fwdUrl); // fwdUrl received from your server after creating an intent
        window.open(url.href).focus();
    };
    ```
  </Step>

  <Step title="Handle Payment Result (Webhook + Redirect)">
    * Once the checkout is completed, xPay will send a **webhook** to the Merchant Server with the final payment status:
      * [intent.success](/developer-resources/webhooks/events/intentEvents/success) for successful payments
      * [intent.failed](/developer-resources/webhooks/events/intentEvents/failed) for failed payments
      * Both webhooks include the `xIntentId` and other relevant payment details.
    * Simultaneously, the customer will be redirected to your configured **callbackUrl** with the query parameter **xpay\_intent\_id**.
    * Your Merchant Frontend should display the final result based on the status already received via the webhook.

    ```javascript JavaScript theme={null}
    const onPageLoad = async () => {
        const url = new URL(window.location.href);
        const intentId = url.searchParams.get("xpay_intent_id");

        // At this point, your backend has already received the webhook.
        // You can show a confirmation page, or query your backend if needed.
        const status = await fetch(`/payment-status?xpay_intent_id=${intentId}`);
        
        if(status === "SUCCESS") {
            // redirect to your payment success page
        } else {
            // redirect to your payment failure page
        }
    };
    ```

    <Note>
      Always trust the **webhook** as the source of truth for payment status. The redirect is primarily for user experience.
    </Note>
  </Step>
</Steps>

***

By following this process, you can integrate xPay's payment gateway into your website, ensuring reliable status tracking via **webhooks** and a seamless customer redirect flow.

***