Authentication

Authentication

UniPayment API use HMAC mechanism to authenticate client requests.
Then HMAC signature must be set in the Authorization header of the request sent from your backend server.

API requests to private resource without authentication will fail. It is also important to note that all API requests must be made over HTTPS.

HMAC signatures

First, the client needs to create a string (MAC – Message Authentication Code) which will contain all the request data that the client wants to send to the server. Generally, the string contains the following parameters:
   AppId
   HTTP method
   Request URI
   Request timestamp
   Nonce
   Base 64 string representation of the request payload (request body)

Note:

Here, we need to calculate the Request Time Stamp value by using the UNIX time (number of seconds since Jan. 1st 1970). We need to do this to overcome the possibility of different time zone issues between the client and the server.

The Nonce is a random number or string which is used only once per request. Here we are going to use GUID to create Nonce.

Once the string is generated by combining all the parameters, then it is the responsibility of the client to generate a HASH (unique signature) of the above string by using SHA256. The important thing here you need to remember is that while generating the unique signature (hash), you need to use the Private Secret API Key which was initially generated when payment app is created.

Once the unique signature (hash) is generated by the client, then the client needs to send that signature (hash) in the request header using a custom scheme such as “hmac” in Authorization header.

The data in the header will contain the public shared APP Id, the request time stamp, the nonce and the Timestamp separated by a colon ‘:’. The format for the Authorization header should be as shown below:

📘

Header fromat

[Authorization: hmac APPId:Signature:Nonce:Timestamp]

Code Example

static string Sign(string appId, string apiKey, string requestHttpMethod, string requestUri, ulong requestTimeStamp, string nonce, string requestContentBase64String)
        {
            var signatureRawData = $"{appId}{requestHttpMethod}{requestUri}{requestTimeStamp}{nonce}{requestContentBase64String}";

            var apiKeyBytes = Encoding.UTF8.GetBytes(apiKey);
            var signature = Encoding.UTF8.GetBytes(signatureRawData);

            using (var hmac = new HMACSHA256(apiKeyBytes))
            {
                var signatureBytes = hmac.ComputeHash(signature);
                var requestSignatureBase64String = Convert.ToBase64String(signatureBytes);

                // Setting the values in the Authorization header using custom scheme (Hmac)
                return $"{appId}:{requestSignatureBase64String}:{nonce}:{requestTimeStamp}";
            }
        }

def sign_request(self, app_id, api_key, request_http_method, url, query_params, request_body=None):
        """Create the HMAC SHA-256 Signatute
        :param string: app_id.
        :param string: api_key.
        :param string: request_http_method.
        :param string: query_params.
        :param string: request_body.
        :return: hmac.
        """
        uri = url
        if query_params is not None:
            uri += '?' + urllib.parse.urlencode(query_params)

        uri = urllib.parse.quote(str.lower(uri), safe='')

        request_body_based64 = ''
        if request_body is not None:
            request_body_json = json.dumps(request_body)
            md5_hash = md5(request_body_json.encode('utf-8')).digest()
            request_body_based64 = b64encode(md5_hash).decode('utf-8')

        nonce = uuid.uuid4().hex
        request_timestamp = int(time())

        raw_data = '{}{}{}{}{}{}'.format(app_id, request_http_method, uri, request_timestamp, nonce,
                                         request_body_based64)
        signature = hmac.new(api_key.encode('utf-8'), msg=raw_data.encode('utf-8'), digestmod=hashlib.sha256).digest()
        return '{}:{}:{}:{}'.format(app_id, b64encode(signature).decode('utf-8'), nonce, request_timestamp)

public static String sign(String appId, String apiKey, String requestHttpMethod, String requestUri, long requestTimeStamp, String nonce, String requestContentBase64String) {
        String signatureRawData = appId + requestHttpMethod + requestUri + requestTimeStamp + nonce + requestContentBase64String;
        byte[] hmac = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, apiKey.getBytes(StandardCharsets.UTF_8)).hmac(signatureRawData);
        String requestSignatureBase64String = Base64.encodeBase64String(hmac);
        return appId + ":" + requestSignatureBase64String + ":" + nonce + ":" + requestTimeStamp;
    }

See also

HMAC authorization Web API