Message structure

2022-01-28 08:09

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. The following diagram shows the structure of an HTTP request.

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. In ZOLOZ gateway protocol, the following header fields are included:

Request-Time (Required)

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

the date/time string that follows the RFC 3339 datetime standard
the timezone string that follows the RFC 822 timezone standard

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

Content-Type (Required)

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

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

For more information about the Content-Type field, refer to RFC 7231.

Client-Id (Required)

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.

Signature (Required)

Specifies the information about the signature of the message. The value of the field is a comma separated list of a combination of the following 2 key-value pairs:

algorithm : the algorithm that is used for signing a request. Only RSA256 is accepted.
signature : the content of the signature. The value of this key must be encoded in Base64.

The following example shows what a valid signature header field looks like.

copy
signature: algorithm=RSA256, signature=IpmAgtDqkjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCkw==

For more information about signing a request and validating a signature, see Message signing and signature validation.

Encrypt (Optional)

The information about the encryption of the message. The value of the field is a comma separated list of a combination of the following 2 key-value pairs:

algorithm : the algorithm used for encrypting a request. Only RSA_AES is accepted.
symmetricKey : the AES key that is encrypted with RSA. The value of this key must be encoded in Base64.

The following example shows what a valid encrypt header field looks like.

copy
encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

For more information about encrypting and decrypting a request, see Message encryption and decryption.

Request Body

The request body is used to carry the content of the request message, which contains the input parameters for an API. The format of the content is different depending on whether the request is encrypted.

If the request is not encrypted, the message content is a string that is in the JSON format. For this case, the Content-Type header filed must be set to application/json.
If the request is encrypted, the message content is a string that is encoded in Base64 on the encrypted data. For this case, the Content-Type header filed must be set to text/plain.

For more information about the detailed content structure, refer to the API specification for each API.

Full HTTP request examples

Two examples are provided below for unencrypted and encrypted request body.

Unencrypted request example

copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m

{
  "title": "hello",
  "description": "just for demonstration."
}

Encrypted request example

copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: text/plain; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m
Encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

r8w8wbc8Nv6sC2meJzArtGjDkbiAzg55UaDiq7TId1a7uzcv18qpOxVkXvqa3q/6TPemDDItZ79oHMzDJyvAngYqfpZZaedArWPCDeddqUl62zU5VwaB1NVhNmjHLNQ6bA1LxpsnMGnb6n8iWAEU4MtJ3TpXerMY6RToSBbI/IBA4MJFbXds0z6XLqQh9XNrLL/J0FUSV0XGFiBRxVMvUP2ytzEKh9HE6fqX/ZqTqadtp89PRTJZM87Rkb3oPdJAlaM7JUaIznGrtKe45UwjtrdYk86QhOmpWXj4L2g0Gww=

Response structure

Response from ZOLOZ is a standard HTTP response, which is composed of HTTP status, header, and body. The following diagram shows the structure of an HTTP response.

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

Trace-Id

Specifies the unique ID that is generated for each API invocation.

Response-Time

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

the date/time string that follows the RFC 3339 datetime standard
the timezone string that follows the RFC 822 timezone standard

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 two content types are supported:

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

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

Signature

Specifies the information about the signature of the message. The value of the field is a comma separated list of a combination of the following 2 key-value pairs:

algorithm : the algorithm that is used for signing a request. Only RSA256 is accepted.
signature : the content of the signature. The value of this key must be encoded in Base64.

The following example shows what a valid signature header field looks like.

copy
signature: algorithm=RSA256, signature=QexLgtKpdjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCky++

For more information about signing a response and validating a signature, see Message signing and signature validation.

Encrypt

The information about the encryption of the message. The value of the filed is a comma separated list of a combination of the following 2 key-value pairs:

algorithm : the algorithm used for encrypting a request. Only RSA_AES is accepted.
symmetricKey : the AES key that is encrypted with RSA. The value of this key must be encoded in Base64.

The following example shows what a valid encrypt header field looks like.

copy
encrypt: algorithm=RSA_AES, symmetricKey=HnI+keXgI9eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC00++

For more information about encrypting and decrypting a response, see Message encryption and decryption.

Response Body

The response body is used to carry the content of the returned message, which contains the output parameters of an API. The format of the content is different depending on whether the response is encrypted.

If the response is not encrypted, the message content is a string that is in the JSON format. For this case, the Content-Type header filed must be set to application/json.
If the response is encrypted, the message content is a string that is encoded in Base64 on the encrypted data. For this case, the Content-Type header filed must be set to text/plain.

For more information about the detailed content structure, refer to the API specification for each API.

Full HTTP response examples

Two samples are provided as below in terms of whether the response body is encrypted.

Unencrypted response example

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: algorithm=RSA256, signature=SGnqy/sC1sbrfK+jAl0ATJwtqUg4jUhkqpPheEYPgnM+20P69NsdrL8BB/ml5ehfFVzsst1bzwEYpDNZvqqNSBo2BPVg78pjJEk0GGNIu7NQ/pyRncYy3pIIXvr91lIvINysHcw8AgUEXRLtjMf1ktQN2OsA3+OFKB6Cf7BrKNnxjeF1lSjzbTk2ua+z1unGHUOeA9GBloSL3rL8ngC/Zqn24/eHWyKJrMFnq1jv+IhOVCqeY4knVFcPgp/bFBs4gyTdE1G1fCK5xmzk9Co8dK0wr6KcC872evBGz7SCMYZCn6Y8O5uRqS9I6F26yKKdqw8PZv2rlwJFsX21l7wRSQ==

{
  "title": "hello",
  "description": "just for demonstration."
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}

Encrypted response example

copy
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Response-Time: 2019-02-23T01:45:57+0000
Signature: algorithm=RSA256, signature=imNNW52LHemfAiUFqek4QQg3ZkdHBGEUOs2SBx0OxPGBIBC0bmpu0%2BviBH%2Bh9w86VTooveJmKQSBVIf0i7hQWXqyd5Qibz49d4k9AhIhTjBKQF1VZTlJUrlphWvisSa9zn5wl3P74v9Z4CDVvHfL3wZzfwg8ujo13nSYjYdsswhSZwkGUgkSCDjq2ObtsPMHG6ZRuzrTjW6tCrqTe6EY4HyHg1mWnsAj12i1b%2FnKNayP%2FCpAe%2BT0%2Fn66NeLGjR9hjTYJ8XKKNoZ5vW%2BVYjWiDt8XWSb3KEO2Zh5Cofswe85sVPnk2S%2BvbN0nlPNU0zlJJJK6ifoSyl%2FSKI6Siu05xw%3D%3D
Encrypt: algorithm=RSA_AES, symmetricKey=eXhw3n3fdpfruNv2kh9cJQ4NzqhNhjKjCynAu6Kn92p0WPY77d8DHJV5Y4QE9fShsW%2FYZIVhCtiZSC2bBS%2F1m9HnCwhKiWzKWTwo44J692DU%2B24Yty%2FHTalqD7QWoOOd0HCskrKFHgf4INE9PMskGnZbp4B7yuLmaUEtuo8FIFNB4e%2FCIL1DhBMdsgcYL%2FiWLylNbpXztE8kMVjoEeOsz%2FbBr3Z22A4%2BQveAIDEc5sr9cjkzCB2gJsjNt4bZUWiZfP8BPLV0QEEh9mhmqzprNao2x9DsuShFcjyc3db%2BZcbMOuI8NxI0V%2FwTDi23%2BloH6Q1Mg0QgWFORlJG9da8s7Q%3D%3D

0JR682PMFgoc2ttribGxpl3f/7rNvjwpmoaAvahki1RxWUSO6mKxyQf87OUgQxQULGabLL4Q5vjFx8XvW/ugvpFexfqLojDeMgNMTyJpkT8=