Environment Setup

Go2Joy API URL

Environment	URL	Rate Limiting
Staging	https://staging-partner.go2joy.vn	~250 requests/ minute
Production	https://partner.go2joy.vn	~500 requests/ minute

• Merchant provides IP for whitelist

• APIs are calling via POST

• APIs has Authorization by provide the signature via Authorization header

• APIs provides 2 languages (Vietnamese, English) via Localization header

• APIs needs default parameters: clientId, timestamp

Type	Parameters	Description
Header	Authorization*	Signature of partners
Header	Localization	The language for title (en, vi). Default is en
Body	timestamp*	The current timestamp when calling api. Expires in 5 minutes.
Body	clientId*	A secret key is distributed to partner.

How to configure authentication

1. Prerequisites

• You already have client id and client secret key.

• You already have a public app or web application.

2. Signature algorithm

Go2Joy verifies the identity of each API request, and the server will also verify whether the call parameters are valid. Therefore, each HTTP request must contain the signature information. The requests with invalid signature will be rejected.

This part explains how to generate an HMAC-SHA256 signature for an HTTP request. The request used to demonstrate signing is a POST (except list of Feed APIs) to https://partner.go2joy.vn/api/v1/hotel/getHotelInfo. The raw request looks like this sample:

POST /api/v1/hotel/getHotelInfo HTTP/1.1
Host: partner.go2joy.vn
Content-Type: application/json
Authorization: 92db273a6b27703a72d828ff0ddf28fe26c2b0cc00c53ea7b354fb8460ce72e1

{"hotelSn":467,"clientId":"8eabbb1b-feb7-4d12-b8fd-10046769a100","timestamp":1626261920,"deviceEncode":"52660884ecdfeafff221ad8e1973f2e7","bookingType":1}

3. Creating the signature base string

The two values collected must be joined to make a single string, from which the signature will be generated. This is called the signature base string.

Sort all request parameters according to the parameter name in ASCII table.

Example:

• Before sort:

{"hotelSn":467,"clientId":"8eabbb1b-feb7-4d12-b8fd-10046769a100","timestamp":1626261920,"deviceEncode":"52660884ecdfeafff221ad8e1973f2e7","bookingType":1}

• After sort:

{"bookingType":1,"clientId":"8eabbb1b-feb7-4d12-b8fd-10046769a100","deviceEncode":"52660884ecdfeafff221ad8e1973f2e7","hotelSn":467,"timestamp":1626261920}

The signature base string is formed by concatenating URL, |, raw HTTP body (raw HTTP body must be encoded).

https://partner.go2joy.vn/api/v1/hotel/getHotelInfo|{"bookingType":1,"clientId":"8eabbb1b-feb7-4d12-b8fd-10046769a100","deviceEncode":"52660884ecdfeafff221ad8e1973f2e7","hotelSn":467,"timestamp":1626261920}

There should be no space in the base string.

4. Client secret key

A secret key is distributed to partner when the registration is completed. Please keep the key as secret as your account password. Never disclose the key to anyone else.

5. Calculating the signature

Finally, the signature is calculated by passing the signature base string and client secret key to the HMAC-SHA256 hashing algorithm. The details of the algorithm are explained in depth here.

The output of the HMAC signing function is a binary string. This needs to be hex encoded to produce the signature string.

hash_hmac('sha256',<YOUR_SIGNATURE_BASE_STRING>,<YOUR_CLIENT_SECRET>)

Example:

hash_hmac('sha256','https://partner.go2joy.vn/api/v1/hotel/getHotelDetail|{"bookingType":1,"clientId":"8eabbb1b-feb7-4d12-b8fd-10046769a100","deviceEncode":"52660884ecdfeafff221ad8e1973f2e7","hotelSn":467,"timestamp":1626261920}','f066739601bd38b6a6cc35a08ebf74bf0c2a77a5')

Sample code for PHP:

<?php
    const CLIENT_ID = '8eabbb1b-feb7-4d12-b8fd-10046769a100';
    const CLIENT_SECRET = 'f066739601bd38b6a6cc35a08ebf74bf0c2a77a5';

    $url = 'https://partner.go2joy.vn/api/v1/hotel/getHotelInfo';
    $body = [
        'timestamp'    => time(),
        'hotelSn'     => 467,
        'bookingType' => 1,
        'deviceEncode' => '52660884ecdfeafff221ad8e1973f2e7',
        'clientId'     => self::CLIENT_ID,
    ];
    ksort($body);
    $bodyToJson = json_encode($body);
    $signature = hash_hmac('sha256', trim($url . '|' . $bodyToJson), self::CLIENT_SECRET);

    $headers['Authorization'] = $signature;
    $headers['Content-Type'] = 'application/json; charset=UTF-8';
    $headers['Localization'] = 'en';
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    try {
        $result = curl_exec($ch);
        $curlErrno = curl_errno($ch);
        $curlError = curl_error($ch);
        if ($result === false || $curlErrNo > 0 || $curlError) {
            echo $curlErrNo . PHP_EOL;
        } else {
            echo $result . PHP_EOL;
        }
        curl_close($ch);
    } catch (\Exception $e) {
        echo $e . PHP_EOL;
    }
?>