Authentication

All Merit API calls require API credentials for authentication:

  • Api Id
  • Api Key

These credentials are used to calculate a unique signature to every API request. This signature is used to authenticate given request to your company and ensure message integrity.

How to obtain API credentials?

For your company, you’ll be given a unique Api ID and Api Key. The admin user can  generate and reset API ID and Key on the Settings >> API Settings.

Keep your Api ID and Api Key secret. They should be guarded just as you would your regular account password. If you feel your ID and Key has been compromised, you can reset it by deleting and re creating a new ID and Key.

How to authenticate with API credentials?

All API endpoints require the following parameters as HTTP query string parameters:

  • apiId
  • timestamp
  • signature

Parameter: apiId

Api Id from API credentials.

Parameter: timestamp

Represents the moment in time given request is sent.

  • MUST use numeric format yyyyMMddHHmmss. See format syntax definitions here.
  • MUST use UTC time.
  • MUST use current time. Requests with invalid timestamps (too old or in future) will be rejected.

NB! DO create new timestamps when using delayed retry mechanisms, i.e. in case of HTTP429 throttling event handling.

Parameter: signature

Signature is calculated using HMAC-SHA256 algorithm (see RFC-2104) using your company secret Api Key as shared secret.
Signed data:

  • Api Id parameter value
  • Timestamp parameter value
  • HTTP request body (if any).

Signature calculation algorithm:

dataToSign := utf8_to_bytes( string_concat (apiId, timestamp, httpBody));
hmacKey := ascii_to_bytes(apiKey);
signatureBytes := hmac_sha256(hmacKey, dataToSign)
signature := base64(signatureBytes)

NB! Signature may contain characters which must be url-encoded when passed via query string!

Example

Input:

Api id670fe52f-558a-4be8-ade0-526e01a106d0
Api keyAoCmZGUfWMMhLJ+Eb6oRF4pAEw9XJP9b/RL5c2Gqk2w=
EndpointPOST /api/v1/getcustdebtrep
Http body to send{
    “CustName”: “Kliendinimi”,
    “CustId”: “3a274294-9c60-4a3d-93f0-1874253f073e”,
    “OverDueDays”: 5,
    “DebtDate”: “20220501”
}
Current time:
24th of June, 23:59:02 in EEST (UTC+3)

Calculated timestamp: 20240624205902
Calculated base-64 encodedsignature: gHvic7vnU6kQfhh6+bY3fjtUzQ+Dpf09PpNgV8ycDC0=

Signed request url:
POST /api/v1/getcustdebtrep?apiId=670fe52f-558a-4be8-ade0-526e01a106d0&timestamp=20240624205902&signature=gHvic7vnU6kQfhh6%2BbY3fjtUzQ%2BDpf09PpNgV8ycDC0%3D