Message structure

    Messages consist of requests from merchants to the ZOLOZ server and responses from the ZOLOZ server to merchants. 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.

    image.png

    #Request-URI

    Specifies the resource upon which to apply a request. The format of this header field value is /api/{version}/{path}, 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 about 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:

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

    #Content-Type (Required)

    Specifies the media type of the request body that is sent to the 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, see RFC 7231.

    #Client-Id (Required)

    Specifies the client identifier that is assigned to a merchant. The ID is generated by the ZOLOZ server and guaranteed to be unique for each merchant. 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, 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 of 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 samples

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

    #Non-encrypted request sample

    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 sample

    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

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

    image.png

    #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:

    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 samples

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

    #Non-encrypted response sample

    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 sample

    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=