Authentication

A MinnaApiKey header is required in every request sent to the Merchant API for authentication purposes.

Security Scheme Type

API Key

Header parameter name:

MinnaApiKey

You can obtain your API key by contacting Minna.

Signature verification

Every request sent to the registered webhook should be verified. When you subscribe to webhook events, the response will include a secret that you should store safely in your system.

📘

Note

This secret will only be sent when a webhook is first created. If it is lost or not saved at that time, you will have to delete and recreate the webhook to be able to verify requests!

Minna will sign all request payloads with this secret and include the signature in the header. The payload will use UTF-8 encoding and without whitespaces so for example:

{
  "id": "eea6bf1c-0ae9-45af-88be-15a90cb8e708",
  "createdAt": "2018-12-03T10:15:30+01:00",
  "desiredCancellationDate": "2019-03-03T10:15:30+01:00"
  "eventType": "cancellation.requested",
  "data": {
    "thisIsAnArray": ["value1", "value2"],
    "thisIsAText": "These white spaces should of course remain"
  }
}

will first be minimized like this:

{"id":"eea6bf1c-0ae9-45af-88be-15a90cb8e708","createdAt":"2018-12-03T10:15:30+01:00","eventType":"order.created","data":{"thisIsAnArray":["value1","value2"],"thisIsAText":"These white spaces should of course remain"}}

The signature is an HMAC generated hash with SHA256 algorithm using the shared secret as key and the compact UTF-8 payload as the message.
The signature is then base64 encoded and added to the request header with header name Signature.

Code example:

// Create MAC instance
val mac = Mac.getInstance("HmacSHA256")
// Create key for signature
val secretKeySpec = new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256")
// Initialize mac instance with key
mac.init(secretKeySpec)
// Minimize payload, i.e. remove all white spaces but not those contained in values.
val minimizedPayload = minimizePayload(payload)
// Generate the hash signature
val hash = mac.doFinal(minimizedPayload.getBytes("UTF-8"))
// Base 64 encode the hash signature
val signature = Base64.getEncoder.encodeToString(hash)
import crypto from 'crypto';

// Generate the hash signature
const hash = crypto.createHmac('SHA256', key).update(payload);

// Base 64 encode the hash signature
hash.digest('base64');

Did this page help you?