Checkout Flow Description

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.
The Checkout Session will provide a URL for the checkout page. You should redirect the customer to this Subotiz-hosted checkout page.
The customer will enter their payment information and complete the transaction on the Subotiz checkout page.
After the transaction is completed, Subotiz will notify your server via a webhook.

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

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 pricing_id of the product pricing to dynamically retrieve product information. Create a Product:

Create Product Pricing:

Step 2: Provide Success and Cancel URLs

Your application needs to prepare two publicly accessible page URLs:

∙A URL for customers to be redirected to after a successful payment.

∙A URL for customers to be redirected to if they cancel the payment.

(Note: The same URL can be used for both purposes.)

Step 3: 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 endpoint. You can use these events to keep your system's business data in sync.

Step 4: 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 to create a 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

curl --location 'https://api.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Hub-Timestamp: 1756513740897' \
--header 'Hub-Access-No: 77d52a21dc032b4' \
--header 'Request-Id: 9913dca8-90f8-4e20-98bc-565f0222ffa8' \
--header 'Hub-Signature: 75c8bfd1cac3c68d2bcf05bc36c913e36577d8d97bc08fba9ce67551808480eb'
--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.

Example Checkout Page:

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