Quick Start

This guide walks you through the foundational integration of Subotiz’s payment capabilities using our Hosted Checkout solution (hosted mode) to quickly implement a payment flow. Subotiz provides complete payment capabilities that support core features such as subscription management and transaction processing, making it suitable for various business scenarios including AI platforms, SaaS applications, and more.

Prerequisites

Have a registered Subotiz merchant account（signup url）
Have completed the Subotiz payment gateway setup and payment method configuration
Have created products and pricing

Integration Steps

Obtain Access Credentials

1. Configure Payment Callback URLs

return_url: Redirect URL after payment success — the default value when using the API to create a checkout session.
cancel_url: Redirect URL after payment cancellation — the default value when using the API to create a checkout session.

Priority rule: URLs supplied at session creation override the defaults set here. We recommend setting a global default here for convenience, and passing a custom URL via the API for specific scenarios.

2. Obtain the Platform Access Information

access_no: Unique identifier for the integrating party
merchant_id: Unique merchant identifier
API Key: API authentication key. See Authentication for how to obtain it (Keep strictly confidential, never expose on the client-side)

Obtain Product Information

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 Checkout Session

Use the API to create a checkout session, retrieve the payment page URL, and guide the customer through completing the payment.Request example:

curl --location 'https://api.sandbox.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_api_key}' \
--header 'Request-Id: 07949371-7868-2282-78af-2a8d5c043760' \
--data-raw '{
  "access_no": "{Your access_no}",
  "sub_merchant_id": "{Your merchant_id}",
  "order_id": "test_order_001",
  "email": "[email protected]",
  "line_items": [
    {
      "price_id": "{Product pricing ID}",
      "quantity": "1"
    }
  ],
  "return_url": "https://your-app.com/success",
  "cancel_url": "https://your-app.com/cancel"
}'

Test Payment Completion

1. Obtain the payment page URL

Upon a successful API response, obtain data.session_url (the payment page URL).

2. Open the checkout page

Access this link in a browser to view the Subotiz-hosted checkout page.

3. Complete payment with a test card

Use the following test card numbers (for Subotiz Payments):

Payment success: card number 4242424242424242, any 3-digit CVC, any future expiration date
Payment failure: card number 4000000000000002, any 3-digit CVC, any future expiration date

Handle Payment Result Notifications

1. Redirect back to return_url

After payment completes, the user is redirected back to the return_url (success scenario).

2. Receive the Webhook notification

Subotiz also sends a Webhook notification to your endpoint (event type trades.succeeded).

3. Verify the Webhook Signature

Extract parameters: obtain the X-Timestamp from the request headers (denoted as timestamp), and get the raw request body content (denoted as body).
Construct the signature string: format is ${timestamp}.${body}.
Compute the signature: using the API Key assigned by Subotiz as the key, compute the signature value via the HMAC-SHA256 algorithm (see the example below).
Compare and verify: compare the calculated signature with the X-Signature value from the request headers. If they match, the request is legitimate.

// Compute Signature
func CalcSignature(timestamp int64, body []byte, secret string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(fmt.Sprintf("%d", timestamp)))
    mac.Write([]byte("."))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

Verifying the Result

Log in to the Subotiz merchant platform to review transaction records and subscription records.
Verify that the order amount and product information are correct.

Integration Guide

AI Developer

Developer Resources

Webhook

Quick Start

Prerequisites

Integration Steps

1. Configure Payment Callback URLs

2. Obtain the Platform Access Information

1. Obtain the payment page URL

2. Open the checkout page

3. Complete payment with a test card

1. Redirect back to return_url

2. Receive the Webhook notification

3. Verify the Webhook Signature

Verifying the Result

​Prerequisites

​Integration Steps

​1. Configure Payment Callback URLs

​2. Obtain the Platform Access Information

​1. Obtain the payment page URL

​2. Open the checkout page

​3. Complete payment with a test card

​1. Redirect back to return_url

​2. Receive the Webhook notification

​3. Verify the Webhook Signature

​Verifying the Result

Prerequisites

Integration Steps

1. Configure Payment Callback URLs

2. Obtain the Platform Access Information

1. Obtain the payment page URL

2. Open the checkout page

3. Complete payment with a test card

1. Redirect back to return_url

2. Receive the Webhook notification

3. Verify the Webhook Signature

Verifying the Result