Quick Start

Prerequisites

1. Have a registered Subotiz merchant account（signup url）
2. Have completed the Subotiz payment gateway setup and payment method configuration

Quick Integration Steps

Step 1: Obtain Access Credentials

1. Log in to the Subotiz merchant platform

2. Obtain the access information provided by the platform:

   • access_no: Unique identifier for the integrating party
   • merchant_id: Unique merchant identifier
   • access_secret：API authentication secret key（​​Keep strictly confidential, never expose on the client-sid）
   

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

​​Create Product Pricing:​​

Step 3: 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.stg.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Hub-Timestamp: {The timestamp used for generating the signature}' \
--header 'Hub-Access-No: {Your access_no}' \
--header 'Request-Id: 07949371-7868-2282-78af-2a8d5c043760' \
--header 'Hub-Signature: {Generated signature}' \
--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",
  "callback_url": "https://your-app.com/webhook"
}'

​​Signature Generation Instructions​​

1. Signature string format: {HTTP Method}\n{Request Path}\n{Timestamp}\n{Request Body}\n

Example (POST request):

func (ha *HmacAuth) CalcSignature(method string, url []byte, timestamp string, body []byte, secret string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(method))
	mac.Write([]byte("\n"))
	mac.Write(url)
	mac.Write([]byte("\n"))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("\n"))
	mac.Write(body)
	mac.Write([]byte("\n"))
	return hex.EncodeToString(mac.Sum(nil))
}

2. Calculate the signature using the access_secret via the HMAC-SHA256 algorithm, and populate the Hub-Signature header.

Example:

func  CalcSignature(method string, url []byte, timestamp string, body []byte, secret string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(method))
	mac.Write([]byte("\n"))
	mac.Write(url)
	mac.Write([]byte("\n"))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("\n"))
	mac.Write(body)
	mac.Write([]byte("\n"))
	return hex.EncodeToString(mac.Sum(nil))
}

Step 4: Test Payment Completion

1. Upon successful API response, obtain the data.session_url(payment page URL)
2. Access this link in a browser to view the Subotiz-hosted checkout page
3. Use the following test card numbers to complete payment testing（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

Step 5: Handle Payment Result Notifications

1. Upon payment completion, the user will be redirected to the return_url(success scenario).

2. Simultaneously, Subotiz will send a Webhook notification to your callback_url(event type trades.succeeded).

3. Verify the Webhook's legitimacy:

   1. Extract Parameters:​​ Obtain the X-Timestamp from the request headers (denoted as timestamp), and get the raw request body content (denoted as body).

   2. ​​Construct Signature Original String:​​ Format is ${timestamp}.${body}.

   3. ​​Compute Signature:​​ Using the access_secret assigned by Subotiz as the key, compute the signature value via the HMAC-SHA256 algorithm.

      Go

        // 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))
        }

   4. Compare and Verify:​​ Compare the calculated signature with the X-Signature value from the request headers. If they match, the request is legitimate.

Verifying the Result

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