ZOLOZZOLOZDOCS

Message structure

Messages consist of requests from the end client to ZOLOZ server and responses from ZOLOZ server to the end client. This section describes the structure of requests and responses.

Request Structure

A request is a standard HTTP request, which is composed of Request-URI, method, header, and body.

Request-URI

Specifies the resource upon which to apply a request. The format of this header field value is /api/{version}/{restfulPath}, where

  • version is the version of the interface, for example, v1.
  • restfulPath is the path to the interface.

Request Method

The only accepted request method is POST.

Request Header

The request header contains additional information about the request, and the client. Under the AK/SK access method, the ZOLOZ gateway protocol includes the following components:

Field

Required

Description

Request-Time

Yes

Specifies the time of the request. The value of this field is a string that is composed of two parts:

For example, 2019-04-04T12:08:56+0530.

Client-Id

Yes

Specifies the client identifier that is assigned to an end client. This ID is generated by ZOLOZ server upon account creation and is guaranteed to be unique for each end client. The value of this field is a 16-digit string.

Content-Type

Yes

Specifies the media type of the request body that is sent to ZOLOZ server. In ZOLOZ gateway protocol, only the following one content type is supported:

  • application/json; charset=UTF-8 : accepted when the request is not encrypted.

Auth-Type

Yes

Fixed value is "AKSK," used to identify that the AK/SK access method is being used.

Access-Key

Yes

Credentials used for authentication and authorization, which can be obtained by the client on the Portal.

Signature

Yes

Specifies the information about the signature of the message.

  • signature : the content of the signature. The value of this key must be encoded in Base64.

Request Body

The request body is used to carry the content of the request message, which contains the input parameters for an API. The message content is a string that is in the JSON format.

Full HTTP request examples

copy
POST /api/v1/zoloz/authentication/test 
Content-Type: application/json;charset=UTF-8
Client-Id: 2188489224744639
Request-Time: 2025-05-12T11:37:16+0000
Auth-Type: AKSK
Access-Key:5pVg7cBioWK0cwYR
Signature:7vEjIzTDZulbMp_y6wrm5306v2wTN4ipRI9JWDuesBY
{
  "title": "hello",
  "description": "just for demonstration."
}

Response structure

Response from ZOLOZ is a standard HTTP response, which is composed of HTTP status, header, and body.

HTTP status

Specifies the processing status of a request. The ZOLOZ gateway protocol uses standard HTTP response codes. For more information, see RFC 7231.

Response Header

Field

Description

Response-Time

Specifies the time of the response. The value of this field is a string that is composed of two parts:

For example, 2019-04-04T12:08:56+0530.

Content-Type

Specifies the media type of the response body that is returned to the merchant. Only the following one content type is supported:

  • application/json; charset=UTF-8 : accepted when the response is not encrypted.

For more information about the Content-Type field, see RFC7231.

Signature

Specifies the information about the signature of the message.

Response Body

The response body is used to carry the content of the returned message, which contains the output parameters of an API. The message content is a string that is in the JSON format. For more information about the detailed content structure, refer to the API Overview.

Full HTTP response examples

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: nXbb7SfBe90o1LtOD8NUq_nY6hf1TPW-_PnyjbENCwg
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "{\"title\":\"hello\",\"description\":\"just for demonstration.\"}",
        "resultStatus": "S"
    }
}