Authentication

Netzme uses OAuth 2 to authenticate requests to the netzme API. Before making a request to the Netzme API, a getToken endpoint request is required to get a token.

Ensure that the data in every request and response cannot be hijacked and imitated by unauthorized users, on every request sent to the Netzme api, it is necessary to include the signature generated using the SHA256-HMAC algorithm.

The following parameters Header must be included in the request header in every API call (except for the Get Token endpoint):

Key	Value
Authorization	Bearer {{ Token }}
Request-Time	{{ Request-Time }}
Signature	{{ Signature }}
Client-Id	{{ Client-Id }}

Authorization

This parameter contains the Token which is obtained from the getToken endpoint and before the token value, it must be preceded by the Bearer. Each token has an active period of 24 hours, and each client only has 1 active token. So that when the request is repeated, the previous token automatically expires.

get Token

POST https://api-dev.netzme.com/oauth/token/accesstoken

For requests to getToken endpoint, there is authentication to ensure that only authorized users can generate token. The Authentication used at this endpoint is Basic Auth, which contains Client Id and Client Secret.

Headers

Name	Type	Description
Authorization*	string	Basic {{ Basic Auth }}
Content-Type*	string	application/json

Request Body

Name	Type	Description
grant_type*	string	value must be "client_credentials"

200

{
    "status": "SUCCEES",
    "username": "institution1",
    "access_token": "4c8e2c551a86c8fa484bdaf47ae690db94da325a335a4e7d191058e6e6280555",
    "token_type": "bearer",
    "expiry_token": 1624856796708
}

401

{
   "status":"UNAUTHORIZED",
   "username":"institution1",
   "expiry_token":0
}

Sample code for generate Basic Auth :

        val credential = StringBuffer()
                .append(clientId)
                .append(":")
                .append(clientSecret)
                .toString()

        val authorizationString = "Basic " + Base64.getEncoder().encodeToString(credential.toByteArray())

Request-Time

This parameter contains the request time in the data type long.

Signature

This parameter contains Signature for ensure that the data in every request and response cannot be hijacked and imitated by unauthorized users.

Payload of signature :

Payload Name	Info	Sample
path	contains path of endpoint plus query	/payment/aggregator/balance?userId=lFi1IiSr
method		POST, GET
requestTime	contains request time in the data type long, must equals with Request-Time in header	1615190625765
body	contains payload of body request.

Sample Raw Payload signature :

path=/payment/aggregator/balance?userId=lFi1IiSr&method=GET&token=Bearer cafebface38fe374af5bcf7579a711658585012507d409eebb74f33fa4684711&timestamp=1615190625765&body=

Salt of Signature :

Salt Name	Info	Sample
client secret	contains client secret	MaREaULkzAUTAFYg
requestTime	contains request time in the data type long, must equals with Request-Time in header	1615190625765
auth	contains authorization, must equals with Authorization in header	Bearer cafebface38fe374af5bcf7579a711 658585012507d409eebb74f33fa4684711

Sample Salt of Signature :

MaREaULkzAUTAFYg-1615190625765-Bearer cafebface38fe374af5bcf7579a711658585012507d409eebb74f33fa4684711

Sample code generate signature :

Java

    private String generateSignature() {
        final long requestTime = DateTime.now().getMillis();
            final String userId = "lFi1IiSr";
            final String auth = "Bearer " + token;
            final String sourceUrl = "/payment/aggregator/balance?userId=" + userId;
            final String method = "GET";
            final String body = "";

            final String plainSignature = buildSignature(sourceUrl, method, auth, requestTime, body);
            final String key = new StringBuilder().append(password).append("-").append(requestTime).append("-").append(auth).toString();
        return hmacSHA256(key, plainSignature);
    }

    private String hmacSHA256(String salt, String bodyMessage) {
        try {
            Mac hmac256SHAInstance = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(salt.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            hmac256SHAInstance.init(secret_key);
            return Hex.encodeHexString(hmac256SHAInstance.doFinal(bodyMessage.getBytes(StandardCharsets.UTF_8)));
        } catch (Exception var4) {
            return null;
        }
    }

    private String buildSignature(String sourceUrl, String method, String auth, long timestamp, String body) {
        return new StringBuilder()
                .append("path=").append(sourceUrl).append("&")
                .append("method=").append(method).append("&")
                .append("token=").append(auth).append("&")
                .append("timestamp=").append(timestamp).append("&")
                .append("body=").append(body).toString();
    }

JavaScript

        var path = "/api/aggregator/merchant/qr/merchant_detail?"
        var phoneNo = "089998887772"
        var method = "GET"
        var token = "dbc8374d7ec49728a1c3f2f12a9da7c33e19e40df6fe6690b46e83f670e4f5ed"
        var timestamp = "1619069444217"
        var body = ""
        var clientSecret = "un17lYTFVuEXzovD"

        var message = "path=" + path + "phoneNo=" + phoneNo + "&method=" + method + "&token=Bearer " + token + "&timestamp=" + timestamp + "&body=" + body
        var keys = clientSecret + "-" + timestamp + "-Bearer " + token
        var hash = CryptoJS.HmacSHA256(message, keys);

        console.log('Plain message : ' + message)
        console.log('Plain key : ' + keys)
        console.log('Hash: ' + hash);