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

# Hosted Page

Subotiz supports completing the checkout process via a hosted page (Hosted Mode). When a customer needs to checkout, you can use the Subotiz API to create a Checkout Session and then redirect the customer to the Subotiz checkout page to complete the entire payment process.

## Checkout Flow Description

1. When a customer is ready to complete a purchase, initiate a checkout request from your **client-side application** to your **server**. Your server should then use the Subotiz API to create a Checkout Session.
2. The Checkout Session will provide a URL for the checkout page. You should redirect the customer to this Subotiz-hosted checkout page.
3. The customer will enter their payment information and complete the transaction on the Subotiz checkout page.
4. After the transaction is completed, Subotiz will notify your server via a webhook.

```mermaid theme={null}
sequenceDiagram
    participant Client as Merchant Client
    participant Server as Merchant Server
    participant SubotizAPI as Subotiz API
    participant SubotizCheckout as Subotiz Checkout

    Client->>Server: 1. Initiate Order
    Server->>SubotizAPI: 2. Create Checkout Session
    SubotizAPI-->>Server: 3. Return Checkout Page URL
    Server->>SubotizCheckout: 4. Redirect Customer to Checkout Page
    note right of SubotizCheckout: 5. Customer Completes Payment
    SubotizCheckout->>Client: 6. Redirect Customer Back to APP
    SubotizAPI->>Server: webhook Notification with Payment Result
```

## Integration Steps

<Steps>
  <Step title="Create a Product">
    Create products and product pricing within the Subotiz merchant platform. Store the product and price information on your server. Creating a Checkout Session relies on the `price_id` of the product pricing to dynamically retrieve product information.

    <Frame caption="Create a Product">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/8dde4ef3-8850f8c0d7752d9788b2a2199ae5f9a28f12cc6a494a71548a73957e-20250901-184228.jpeg?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=48a7e362658755b41676c6b7c72d70fb" width="1913" height="855" data-path="images/8dde4ef3-8850f8c0d7752d9788b2a2199ae5f9a28f12cc6a494a71548a73957e-20250901-184228.jpeg" />
    </Frame>

    <Frame caption="Create Product Pricing">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/5ba6678d-53dec35d10ebc5ed846609583fd381b30b119cbdd72138782e1bfb50-20250901-184452.jpeg?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=f559f1068f084e59a989d49f9e934609" width="1920" height="853" data-path="images/5ba6678d-53dec35d10ebc5ed846609583fd381b30b119cbdd72138782e1bfb50-20250901-184452.jpeg" />
    </Frame>
  </Step>

  <Step title="Provide Success and Cancel URLs">
    Your application needs to prepare two publicly accessible page URLs (the same URL can be used for both):

    * A URL to redirect customers to after a successful payment.
    * A URL to redirect customers to if they cancel the payment.
  </Step>

  <Step title="Provide a Webhook Endpoint">
    Create an endpoint to receive events for your account. When an event occurs (e.g., a successful payment), Subotiz will send an HTTPS POST request containing a JSON-formatted event object to the [Webhook](/en/webhook/introduction-2) endpoint. You can use these events to keep your system's business data in sync.
  </Step>

  <Step title="Provide an Entry Point to Create a Checkout Session">
    Your client-side application needs an entry point to initiate checkout, such as a "Checkout" button on an order preview page. When a customer clicks this button, your server should call the [Subotiz API ](/en/api/introduction-1)to create a [Checkout Session ](/en/api/v1-checkout-session-create-checkout-session). Modify the API call parameters based on the order information. The parameters passed when creating the Checkout Session determine what the customer sees on the checkout page (e.g., product info, order price). After the API responds, redirect the customer to the Subotiz checkout page.

    #### Example: Creating a Checkout Session in Hosted Mode

    ```bash theme={null}
    curl --location 'https://api.subotiz.com/api/v1/session' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {your_api_key}' \
    --header 'Request-Id: 9913dca8-90f8-4e20-98bc-565f0222ffa8' \
    --data-raw '{
    		"access_no":       "77d52a21dc032b4",
    		"sub_merchant_id": "2816433",
    		"order_id":        "123e4567-zzzaa20daw11a",
        "payer_id": "customer_id_0012",
    		"line_items": [
    			{
    				"price_id": "543321366326164797",
    				"quantity": "1"
    			}
        ],
    		"email":           "zhangsan@subotiz.com",
        "integration_method": "hosted",
        "cancel_url": "https://www.subotiz.com",
        "return_url": "https://www.subotiz.com"
    	}'
    ```

    #### Key Parameters

    * `order_id`: Your platform's internal order ID, used for subsequent business data correlation.
    * `integration_method`: Set to `hosted` to use the hosted page integration method.
    * `cancel_url`: The URL the customer is redirected to if they cancel payment on the Subotiz Checkout page.
    * `return_url`: The URL the customer is redirected to after a successful payment on the Subotiz Checkout page.

    <Frame caption="Example Checkout Page">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/817f4033-d916f05797030bb1db5016d117eb340179ac14f8e95184a47215e97e-sample_checkout.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=a3f56b4c26099e6b76375c859508c7a4" width="3834" height="1696" data-path="images/817f4033-d916f05797030bb1db5016d117eb340179ac14f8e95184a47215e97e-sample_checkout.png" />
    </Frame>

    After the customer completes checkout, Subotiz will redirect them back to your success page (return\_url), concluding the checkout flow. Additionally, Subotiz will send a Webhook notification to your server, where you can handle post-payment logic (e.g., activating a subscription).
  </Step>
</Steps>