API Document

# Signature Guidelines

# Signature Description

In order to prevent requests from being tampered with or forged during transmission over the internet, all private interfaces (such as those related to funds or transactions) must perform signature verification.

The signature mechanism ensures that parameters are not tampered with during transmission and effectively prevents replay attacks.

# Request Structure

A legitimate request contains the following key fields (all fields, except secret_key, are passed via the request header):

Parameter Description
access_key API access key that identifies the user
secret_key The key used for signing, which is only displayed when creating the API Key. Keep it safe and do not transmit it
timestamp The timestamp when the request is made (in milliseconds, 13 digits, e.g., 1632811287325), used to prevent replay attacks
nonce A random UUID (e.g., 053a1b81-48a0-4bb1-96b2-60f6e509d911), ensuring request uniqueness
sign The signature string generated through the signing algorithm, used for parameter integrity verification

Except for secret_key, the above fields must all be passed as Header parameters.

# Signature Steps

# Step 1: Define the Parameter Map

Define a dictionary (Map) object and include the business parameters used in the API request in key-value pairs.

# Step 2: Add Public Parameters

Add the following three common parameters to the Map:

  • access_key: Access key
  • timestamp: Millisecond-level timestamp (13 digits)
  • nonce: Random UUID string

# Step 3: Parameter Sorting & Concatenation

Sort all parameters in the Map in ascending order according to ASCII lexicographical order.

Then, concatenate the sorted parameters into a string in the following format:

Copy Codekey1=value1&key2=value2&key3=value3

# Step 4: Generate the Signature (sign)

Use secret_key to perform the following encryption on the concatenated string from the previous step:

  • Encryption Method: HMAC-SHA1
  • Encoding Method: Base64

The final output is the signature parameter sign.

The secret_key is the key you receive when creating your API Key in the merchant platform. It is only shown once, so be sure to keep it safe.

# Step 5: Construct the Request and Send

Add the following fields to the HTTP request header:

Copy Codeaccess_key: your_access_key
timestamp : millisecond timestamp
nonce     : UUID random string
sign      : the signature generated in Step 4

Then send the request to the corresponding API endpoint.

Merchant Signature Flow Diagram

img

# Signature Debugging Tool Usage Instructions

To help developers quickly verify the signature logic, the platform provides the built-in signature debugging tool SignUtil, which supports online signature generation and parameter format verification.

# Access Path

Login to the Cashier Backend → [Developer Center] → [API Documentation] → Click on the [Signature Tool] entry

img

# Instructions

  1. Open the signature tool page;
  2. Enter the business parameters required by the API;
  3. Fill in a valid access_key;
  4. Enter the corresponding secret_key (used for local debugging, will not be uploaded);
  5. Click the "Generate Signature" button to view the calculation result;
  6. Use the generated sign value in the request Header for testing the API call.

img

# Security Recommendations

  • The signature tool is for debugging purposes only. Do not expose your secret_key in the production environment;
  • It is recommended to set the IP whitelist for the access_key used in debugging to 0.0.0.0 for easier testing;
  • It is strongly recommended to discard the access_key used for debugging after testing and create a new Key for production use;
  • Do not use an existing production API Key for debugging to avoid potential risks.

← Interface Connectivity Test →