Basic Guidelines

Basic

• All API requests must use HTTPS, and all HTTP interface methods must be POST.
• Input parameters and fields in response results must follow the camelCase naming convention.
• Character encoding: UTF-8
• All date objects must follow the format defined by ISO 8601.

yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00

WARNING

When making requests, server certificate validation errors must not be ignored to avoid malicious hijacking.

Request Parameters

• When making requests, the HTTP body must be signed, and the signature result should be submitted to the server along with the request parameters for processing. For details, refer to: signature
• Business parameters should be submitted through the HTTP body in JSON format, supporting nested objects. Refer to the specific API descriptions for detailed parameter lists.

Examples:

# For the actual request parameters, please refer to the API documentation on the left menu for details on each API.

curl https://{{gateway_domain}}/v2/payment/create \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb71,sign=7cc24c5ed4eb9b97696260c51d38ce9cf959c242922689885f8b30bc6863a019,timestamp=1715670758482,nonce=CEAE7940ADEEE91C5A1207F1BB78BE7F' \
  -d '{"key1": "value1", "key2": "value2"}'

Response Format

TIP

The response includes the HTTP Status Code, Response Header, and Response Body. Response Body is in JSON format. Merchants should use the HTTP Status Code and the code in the Response Body to proceed with subsequent business logic processing.

The response fields of an API may be expanded based on business requirements.

Error Information

• If the request is successfully received and processed by the gateway, a reply body in JSON format with HTTP status code 200 will be returned.
• If the signature verification fails, a 401 status code will be returned.
• A service system error occurred while the request was being processed, and a status code in the 5xx range will be returned.

Examples

HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb71,sign=7cc24c5ed4eb9b97696260c51d38ce9cf959c242922689885f8b30bc6863a019,timestamp=1715670758482,nonce=CEAE7940ADEEE91C5A1207F1BB78BE7F

{
    "code": "OK",
    "errorMessage": null,
    "data": {
        "key1": "value1",
        "key2": "value2"
    }
}

User Agent

The HTTP protocol requires the requesting client to identify itself with the HTTP header User-Agent in each request. It is recommended that callers choose one of the following two methods:

• Use the default User-Agent of the HTTP client.
• Follow the HTTP protocol and use information such as the name and version of your system and application to form your own unique User-Agent.

The platform may refuse to process requests without a User-Agent.

Notification Mechanism

There are two types of notifications.

Synchronization Notification(urlRedirect)

When the user makes a successful payment, or cancels the payment, the platform will redirect the consumer's browser to the returnUrl provided by the merchant with the relevant parameters. The synchronization notification is redirected in GET mode, and the corresponding parameters are concatenated, and the value of each parameter is encoded as UTF-8 URLEncode, and then redirected.

TIP

Because synchronous redirects can fail (e.g., user closes the browser), we strongly recommend relying on asynchronous notifications to confirm the payment result.

Asynchronous Notifications(webhook)

The platform will send the message of the consumer's payment result to the notifyUrl provided by the merchant through the server, and submit it in the form of POST with relevant parameters.

Merchants need to verify and process the result information accordingly:

• Perform signature verification to prevent forged notification messages.
• Determine the order status based on the returned status field.