Payment | Integrating Embedded Payment Form

Embedded Payment 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 returns 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 enters their payment details into the form and completes 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.

Payment flow for subscription renewals

1. After the customer completes the initial payment, save the payment_token data from the payment success event（trades.succeeded）to initiate renewal charges.
2. Use the Create Trade（Trade） API endpoint in the Subotiz API to initiate the charge.
3. Proactively query the trade order or wait for an asynchronous notification to obtain the payment result, then notify the customer accordingly.

Integration process

Step 1: Provide a Webhook endpoint

Step 2: Integrate the embedded form

1. Load Subotiz.js

<script src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"></script>

2. Provide a container element

<div id="your_domElement">
    <!-- Checkout page will be displayed here -->
</div>

3. Create checkout session

curl --location 'https://api.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Hub-Timestamp: 1755695704350' \
--header 'Hub-Access-No: 77d52a21dc032b4' \
--header 'Request-Id: dd7fb126-be31-4144-a1af-e4bf4203eb92' \
--header 'Hub-Signature: 4830f629ff065be043c4f4b2f908ef6418d18e4ef9d6a288313ded21f1b0ec13' \
--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",
        "return_url":   "https://www.subotiz.com",
        "cancel_url":   "https://www.subotiz.com",
        "callback_url": "https://webhook.site/2c889bcb-9923-4551-909a-d827f1c326e3",
        "mode": "payment",            # Select payment mode when no product data is present
        "total_amount": "10",         # Amount to collect (required for payment mode)
        "integration_method": "embedded",    # Choose embedded integration
        "redirect_on_completion": "if_required" # Configure redirection behavior; this example only redirects when necessary
    }'

• order_id: Your platform's internal order ID for subsequent business data correlation
• integration_method: Set to embedded to use the embedded form integration method
• return_url: URL to redirect customers to after successful payment on the Subotiz Checkout page
• mode: Choose payment mode
• total_amount: Amount for this checkout session

4. Initialize checkout page

// After importing via script tag, Subotiz is automatically attached to window object
const { Subotiz } = window;

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

// Initialize checkout
const checkout = await subotiz.initEmbeddedCheckout({
  fetchSessionId: async () => {
    // Retrieve sessionId from your server
    const response = await fetch('/api/session');
    const data = await response.json();
    return data.sessionId;
  },
  environment: 'TEST', // 'TEST' | '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 page
checkout.mount('#your_domElement');