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

# Embedded Form

Subotiz supports completing the checkout process through an embedded form (Embedded Mode). It provides a low-code payment integration solution, allowing you to easily create customizable payment forms and quickly implement the checkout flow.

## Integration Scenario Demo

This page explains how to implement the Embedded Checkout integration. This method enables you to rapidly implement an integrated checkout experience by leveraging Subotiz's product, pricing, and payment capabilities.

If you only need to integrate payment processing, please refer to [Payment Mode](/en/integration/embedded-form-payment).

#### Embedding a Complete Checkout Page

<Frame caption="Demo of embedding a complete page">
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/cee483fb-2c8904cf62ff30ea77e87dc94963f5e5087a3a107c52ab624e579cbb-20250830-145318.jpeg?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=f9be8455b55694873f532007bd7d8c97" width="2948" height="1700" data-path="images/cee483fb-2c8904cf62ff30ea77e87dc94963f5e5087a3a107c52ab624e579cbb-20250830-145318.jpeg" />
</Frame>

#### Embedding Partial Components

<Frame caption="Demo of embedding partial components">
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/bf6f69c6-767a63ee08ef17927b83fdde843508f726c696261c17739299aa9679-20250830-145624.jpeg?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=2df3d457c6d448a662b3bf1f14fff091" width="1982" height="1336" data-path="images/bf6f69c6-767a63ee08ef17927b83fdde843508f726c696261c17739299aa9679-20250830-145624.jpeg" />
</Frame>

## Checkout Flow

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 use the Subotiz API to create a Checkout Session, passing the `order_id` (your platform's unique order identifier) as a parameter to facilitate subsequent association with the trade order.
2. The Checkout Session will provide a Session ID. Your client-side application can then use the SDKs to invoke and display the Subotiz payment form to the customer.
3. The customer will enter their payment details into the Subotiz form and complete the transaction.
4. After the transaction is completed, Subotiz will notify your server via a webhook. This notification includes a payment success event containing the `order_id` passed during session creation, enabling you to correlate your platform's order with Subotiz's trade order.

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

    Customer->>Client: 1. Initiate Order
    Client->>Server: 2. Request session ID
    Server->>SubotizAPI: 3. Create Checkout Session
    SubotizAPI-->>Server: 4. Return session information
    Server-->>Client: 5. Return session id
    Client->>Client: 6. Invoke Form Using SDKs
    Client-->>Customer: 7. Display Payment Form
    Customer->>Client: 8. Enter Payment Information & Confirm
    Client->>Client: 9. Process Payment
    Client-->>Customer: 10. Return Payment Result
    SubotizAPI->>Server: Webhook Noification with Payment Result
```

## Integration Steps

<Steps>
  <Step title="Create Products">
    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/1c938fff-3169b0e7f65b7fe44464c9c7fcb5a9cd05be44b2dff67e2109484b72-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=48ad1f39aa87d7e1accf80677d0d1270" width="1920" height="853" data-path="images/1c938fff-3169b0e7f65b7fe44464c9c7fcb5a9cd05be44b2dff67e2109484b72-image.png" />
    </Frame>
  </Step>

  <Step title="Provide a Payment Success Page">
    Your application needs to provide a publicly accessible page to display after a successful payment. After the customer completes the payment, Subotiz will redirect them to this page.
  </Step>

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

  <Step title="Integrate the Embedded Form">
    Your client-side application can use the [Subotiz SDK](/en/resources/subotiz-sdk) to integrate Subotiz Checkout.

    #### 1. Load Subotiz.js

    ```html theme={null}
    <script src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"></script>
    ```

    #### 2. Provide a Container Node

    ```html theme={null}
    <div id="your_domElement">
        <!-- The checkout page will be displayed here -->
    </div>
    ```

    #### 3. Create Checkout Session

    Use the [Subotiz API ](/en/api/introduction-1) to create a [Checkout Session ](/en/api/v1-checkout-session-create-checkout-session), and return the response to your frontend.

    **Example: Creating a Checkout Session in Embedded 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: dd7fb126-be31-4144-a1af-e4bf4203eb92' \
    --data-raw '{
            "access_no":       "77d52a21dc032b4",
            "sub_merchant_id": "2816433",
            "order_id":        "123e4567-e89b-12-a456-426622201a",
            "payer_id": "customer_id_001",
            "customer_id":     "",
            "email":           "zhangsan@subotiz.com",
            "line_items": [                        # Product info (required for checkout mode)
                {
                    "price_id": "543321366326164797",
                    "quantity": "1"
                }
            ],
            "return_url":   "https://www.subotiz.com",
            "cancel_url":   "https://www.subotiz.com",
            "mode": "checkout",      # Choose 'checkout' mode when product data is present
            "integration_method": "embedded",   # Select embedded integration
            "redirect_on_completion": "if_required" # Choose redirection behavior based on business needs; this example redirects only when necessary
        }'
    ```

    #### Key Parameters

    * `order_id`: Your platform's internal order ID, used for subsequent business data correlation.
    * `integration_method`: Set to `embedded` to use the embedded form integration method.
    * `return_url`: The URL the customer is redirected to after a successful payment.
    * `mode`: Choose `checkout` mode when product data is present.

    #### 4. Initialize the Checkout Page

    ```javascript theme={null}
    // After importing via the script tag, Subotiz is automatically attached to the window object
    const {
        Subotiz
    } = window;

    // Create an SDK instance
    const subotiz = Subotiz();

    // Initialize checkout
    const checkout = await subotiz.initEmbeddedCheckout({
        fetchSessionUrl: async() => {
            // Fetch the sessionUrl from your server
            const response = await fetch('/api/session');
            const data = await response.json();
            return data.sessionUrl;
        },
        environment: 'SANDBOX',// 'SANDBOX' | 'PRODUCTION'
        // The callback function when the payment completed only triggers when `redirect_on_completion`  is set to `if_required` during Checkout session creation
        onComplete: () => {
            console.log('Payment completed!');
        }
    });

    // Mount to the page
    checkout.mount('#checkout-container');
    ```
  </Step>
</Steps>