Overview

Subotiz OpenAPI uses ​​API Signature​​ for request authentication. When accessing the OpenAPI, you must generate a signature for the request content using a specified algorithm and include the signature value in the request headers. Subotiz will verify this signature value to confirm the legitimacy of the request.

Digital Signature

Prerequisites

You must first obtain the API authentication secret key, access_secret, from the Subotiz merchant platform. This key serves as the core credential for the HMAC-SHA256 signature algorithm and must be kept strictly confidential.

​​Query Key Information:​​

​​Construct the Signature String​​

The signature string consists of four lines, each representing a parameter. It ends with a newline string \n(ASCII code 0x0A), including after the last line. If a parameter itself ends with \n, an additional \n must still be appended.

Line 1: "HTTP Request Method\n"
Line 2: "URL\n"
Line 3: "Request Timestamp\n"
Line 4: "Request Body\n"

Step 1: Obtain the HTTP Request Method

Extract the HTTP method of the request (e.g., GET, POST, PUT, etc.) to form the first line of the signature string. Example:

"GET\n"

Step 2: Process the Request URL

Obtain the absolute URL of the request (e.g., https://xxx.com/api/v1/payment/query?out_trans_id=2024123232323). ​​Remove the protocol and domain parts​​ (i.e., keep only the path and query parameters) to form the URL used for signing. If query parameters are present, include the ? and the subsequent query string. Example:

/api/v1/payment/query?out_trans_id=2024123232323\n

Step 3: Extract the Request Payload Body

Obtain the content of the Request Body based on the request method type:

• ​​GET Requests​​: No request body; use an empty string "" followed by a newline \n.
• ​​POST/PUT Requests​​: Use the actual JSON-formatted request body content sent (must be identical to the content sent).

Step 4: Concatenate the Complete Signature String

Obtain the current timestamp in milliseconds. Combine the four parts according to the rules above to form the complete signature string. Example (GET request):

"GET\n/api/v1/payment/query?out_trans_id=2024123232323\n1754562236502\n\n"

Raw string print example:

GET
/api/v1/payment/query?out_trans_id=2024123232323
1754562236502
             

Signature Value Calculation

Use the HMAC-SHA256 algorithm with the access_secret as the key to hash the signature string, generating the final signature string (signature).

GO Code Example：

// Calculate Signature
func CalcSignature(secret string) string {
    str := "GET\n/api/v1/payment/query?out_trans_id=2024123232323\n1754562236502\n\n"         
    // Create HMAC-SHA256 hasher         
    mac := hmac.New(sha256.New, []byte(secret))         
    // Write the data to be signed         
    mac.Write([]byte(str))
    return hex.EncodeToString(mac.Sum(nil))
}

Signature Verification

Set the calculated signature value in the Hub-Signature field of the request header. Subotiz will recalculate the signature value using the same algorithm and compare it against the Hub-Signature value in the request header to verify the authenticity of the request.