Signature Validation

Payright signature authentication enhances API security by generating a unique signature for every request. This mechanism ensures both the validity and integrity of API interactions. Each signature contains iat (issued at) and exp (expires at) fields, giving merchants flexibility to define the request's expiration timeframe. Merchants can choose to activate or deactivate this feature depending on their specific security preferences.

How to Enable and Disable Signature

Merchants can manage the signature feature by navigating to Account > API Keys > Edit > JWT Verification, where they can enable or disable it as needed.

Guide To Construct Signature Body

Encode JSON Object Using HS256

Once enabled, the system will validate each incoming API request by encoding the following payload using JWT with the HS256 algorithm.

{
    "auth-token": authToken,
    "http_method": "POST",
    "url_path": "/api/v1/example",
    "iat": currentTime,
    "exp": currentTime + 300 // Token expires in 5 minutes
}

The JWT signature example below demonstrates how the payload is encoded using the HS256 algorithm:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoLXRva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LlRGQXRRamd4TmpKRlJUQXRUVTE4TlRJM056bGpNemN0T0dNeU9DMDBNbUpqTFdFek5tUXRNR1kxT0RSaVkyUTJaR1l5ZkRGaU5qWXlNVGN6TkRZMVptTXhZVEU1TkRFelpHRXpaR1JqTmpOak1qRXlZV0ZoTmpJNVpERTJZamhqWmpRMk1tRmxaV1pqWkRZd01qTXlPVGd3TURFeU9XUTVaV1UwTTJVeU5UUmtNelUzTjJFMk0ySXpNR1UyTTJSbU16ZGxZMk0xWlRBMU1EUTVZbVZsWTJNM01UQTBaVEUxWVRGaFl6RmtNVEZsTWpOaS51cm5RNExpZmt5V2JNQzY5c2F4aDlHY203Q3FKcEoxbUs2SjliTW1rMHBZIiwiaHR0cF9tZXRob2QiOiJQT1NUIiwidXJsX3BhdGgiOiIvYXBpL3YxL2V4YW1wbGUiLCJpYXQiOjE3MzU5MzYyNTQsImV4cCI6MTczNTkzNjU1NH0.BmGpRaoehETwBT9SUGFSARHJmYVUaarte0axM_JB7y4

Request Header Injection

Merchant application must generate a JWT-encoded (HS256) signature of the JSON object using the hash key as the secret key. This hash key is available in the Merchant Portal, and the resulting encoded output will be used as the X-Signature. The generated X-Signature is added to the request headers. These headers will contain the following: x-signature: The HMAC-SHA256 signature.

Validation of Signature

The server verifies the X-Signature by reconstructing the message and comparing it with the signature included in the header. If the two signatures align, the request is deemed valid and proceeds for processing.

Sample Header

An example of an API request header with an HMAC signature and supplementary headers is shown below:

POST /api/v1/merchant/bills HTTP/1.1
Host: https://api.payright-sandbox.my/api/v1/merchant/bills
Content-Type: application/json
auth-token : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.TFAtQjgxNjJFRTAtTU18NTI3Nz
x-signature: '{{signature}}