> ## 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 subscription payment flow into your website using xPay’s payment gateway APIs.

```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 MF,MS: Customer clicks Subscribe
    MF->>MS: Create subscription request
    end

    rect transparent
    note over MS,XS: Initialize subscription
    MS->>XS: POST /subscriptions/create { interval, amount, callbackUrl, ... }
    XS-->>MS: { subscriptionId, fwdUrl }
    end

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

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

    rect transparent
    note over XC,XS: Customer completes checkout
    XS->>MS: Webhook subscription.<active> { subscriptionId, status }
    XS-->>MF: Redirect to callbackUrl?subscription_id
    end

    rect transparent
    note over MF,MS: Frontend reads server-confirmed status
    MF->>MS: GET /subscription-status?subscription_id
    MS-->>MF: { status: ACTIVE | TRIALING | CREATED }
    MF-->>MF: Render result page based on status
    end
```

<Steps>
  <Step title="Create Subscription Intent (Merchant Server → xPay Server)">
    From your backend, call the **Create Subscription** API to initialize the subscription.\
    The response contains `subscriptionId` and `fwdUrl`.\
    See [Create Subscription API](/developer-resources/endpoints/subscriptions/create-subscription) for details.

    <Note>
      Set **callbackUrl** to a client page that can read the redirect parameters and show a result screen.
    </Note>
  </Step>

  <Step title="Store Identifiers (xPay Server → Merchant Server)">
    Save the `subscriptionId` along with any correlation IDs.\
    This ensures you can reconcile webhook notifications with customer sessions.

    <Tip>Store only the minimal customer metadata required to render the post-checkout page.</Tip>
  </Step>

  <Step title="Send Data to Frontend (Merchant Server → Merchant Frontend)">
    Return the `fwdUrl` and subscription details to the frontend so the customer can start the checkout flow.

    <Info>Ensure the page is ready to handle navigation and the redirect to your **callbackUrl**.</Info>
  </Step>

  <Step title="Redirect to xPay Checkout (Merchant Frontend → xPay Client)">
    Use the `fwdUrl` to redirect customers to xPay’s subscription checkout page.

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

  <Step title="Receive Webhook Result (xPay Server → Merchant Server)">
    After checkout, xPay sends a **webhook** to your backend with the final outcome:

    * [subscription.active](/developer-resources/webhooks/events/subsEvents/active) for successful subscription creation
    * The webhook payload includes `subscriptionId` and other relevant subscription details.

    <Note>
      Always treat the webhook as the source of truth.\
      Make your webhook handler idempotent and validate the signature.
    </Note>
  </Step>

  <Step title="Handle Customer Redirect (xPay Client → Merchant Frontend)">
    In parallel, the customer is redirected to your **callbackUrl** with `subscription_id` in the query string.\
    The frontend should display the result page using the status already received via webhook.

    ```javascript theme={null}
    const onSubscriptionPageLoad = async () => {
      const url = new URL(window.location.href);
      const subscriptionId = url.searchParams.get("subscription_id");

      // Query your own backend which has stored the webhook result
      const res = await fetch(`/subscription-status?subscription_id=${subscriptionId}`, { credentials: "include" });
      const { status } = await res.json();

      if (["ACTIVE", "TRIALING"].includes(status)) {
        // show subscription success UI
      } else {
        // show failure UI
      }
    };
    ```
  </Step>
</Steps>

***

By following this flow, subscription confirmation is handled via **webhooks** on your backend,\
while the redirect ensures a smooth experience for customers.

***