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

**1. 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](https://docs.xpaycheckout.com/developer-resources/endpoints/subscriptions/create-subscription.md) for details.

> [!NOTE]
>
> Set **callbackUrl** to a client page that can read the redirect parameters and show a result screen.

**2. 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.

**3. 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.

> [!NOTE]
>
> Ensure the page is ready to handle navigation and the redirect to your **callbackUrl**.

**4. 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();
};
```

#### Optional checkout parameters

Append these query parameters to the `fwdUrl` to change how the checkout page looks. Keep every parameter already in the `fwdUrl` and add these to it.

> [!NOTE]
>
> The checkout is currently available in **English and German only**.

| Parameter | Values | What it does |
| - | - | - |
| `locale` | `en`, `de` | Opens the checkout in English or German. These are the only supported languages today. Defaults to the language the customer last chose, otherwise English. Any other value falls back to English. |
| `scfa` | `true`, `false` | `false` hides the convenience fee amount. |
| `hideCloseBtn` | `true`, `false` | `true` hides the checkout's close button. |

```javascript theme={null}
const redirectToCheckout = () => {
    const url = new URL(fwdUrl);
    url.searchParams.set("locale", "de");        // open the checkout in German
    url.searchParams.set("scfa", "false");       // hide the convenience fee amount
    url.searchParams.set("hideCloseBtn", "true");
    window.location.href = url.toString();
};
```

> [!WARNING]
>
> `scfa=false` only hides the fee amount. The convenience fee label stays, the fee remains in the total, and the customer is charged the same. It changes what's displayed, nothing else.

> [!NOTE]
>
> `locale` translates the checkout page only. Emails and some payment errors stay in English.

**5. Receive Webhook Result (xPay Server → Merchant Server)**

After checkout, xPay sends a **webhook** to your backend with the final outcome:

* [subscription.active](https://docs.xpaycheckout.com/developer-resources/webhooks/events/subsEvents/active.md) 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.

**6. 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
  }
};
```

***

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

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.