HMAC

HMAC is the abriviation of Hash-based Message Authentication Code. The handling of messages using HMAC, ensures that a message is not modified during transport. The message is encrypted by means of a secret key and a (small) change is immediately detectable. The development page explains how the calculation takes place.

The structure of the Hash-based code is as follows: HMAC [Websitekey]:[Base64hash]:[Nonce]:[TimeStamp]. The itallic fields in the HMAC represents the following information :

• Website key : to be found in the Buckaroo Plaza at My Buckaroo → Websites

• Base64 hash : the HMAC SHA256 signing is used. The Secret Key will be used for hashing. See the explanation below *

• Nonce : a random chosen string of characters, which should be unique for every request

• TimeStamp : time indication of the moment of posting the request. See the time stamp description below

Fields used in the hash

The values below are ​​used to generate the HMAC SHA256 hash. All these parameters (except the secret key) must be concatenated into one string to generate the HMAC SHA256 hash.

Website key : To be retrieved from the Buckaroo Plaza. Go to My Buckaroo → Websites
Request method : GET of POST in in capitals
Request URI : where will the request be send to? Attention: leave out the https:// part
Request timestamp : the timestamp contains the number of seconds pased after 01-01-1970 (00:00:00:00), this valua is expressed in the UTC tiime zone. UTC stands for Coordinated Universal Time
Nonce : a randomly chosen string of karakters, which must be unique in every request
Request content string : generate a MD5-hash from the raw data of the message. After this convert this hash to a Base64-string. *
Secret Key: character string, entered in the Buckaroo Plaza. This value will be used to decode and check the send messages. The Secret Key can be found at Settings → Secret Key. If not filled in: please supply a random string of characters and numbers

Debugging

The Buckaroo Authentication Debugger can be used to calculate the HMAC. The calculated value can be compared with the outcome of the own build calculation functionality. If the Execute button is used in de debugger, the calculation will be made. At the right half of the screen the explanation on the calculation will be given. The values of the steps in between will be shown like :

1. MD5 hash from the message content
2. Base64 string from the MD5 hash
3. Concatenation result of the websiteKey, httpMethod, requestUri, timeStamp, nonce + encodedContent
4. The Hmac SHA256 hash from the concatenated string, signed with the secret key
5. The Base64 from the HmacSHA256 hash
6. The complete authorization header : HMAC

Signature calculation

The Buckaroo .NET SDK specifies how the signature of a message can be calculated before sending and verified upon receipt of the messages. In this way it is easy to check whether the message has been sent by Buckaroo and arrived unedited at the Push URL. Use the button below to go directly to the SDK.

JAVA implementation

The following points of attention are applicable when JAVA is used to implement the Buckaroo Payment solutions. The checkout of Buckaroo hosts an example for java encoding. The following examples of implementation issues are good to take notice of:

Hash

The Base64 on the MD5 hash is often calculated by standard JAVA components. The requested output can sometimes not be delivered by these components. The example code in a ZIP for java describes how the signature can be calculated. By comparing this example with the own written code, the developer of the functionality can distinguish the way the logic should be build up.

Timestamp

First of all: please take notice of the way the Timestamp calculation is build up in java. Please consult the website of TecAdmin for this. For calculating the local timestamp it does not matter if the local London or Amsterdam time is used. The most common issue is the calculation to be done in seconds : do not use milliseconds. An unix timestamp works on the time difference in seconds between 1 jan 1970 (epoch) and now. In java this time is normally withdrawn in milliseconds. Therefore the result should be divided by 1000. If this is forgotten, the result is 1000 time bigger and it looks as if the message comes from a moment in the very far future. The following example code can help the developer out on this:

// EXAMPLE FOR THE CALCULATION OF THE UNIX TIMESTAMP.
// A UNIX TIMESTAMP IS THE TIMESPAN BETWEEN THE UNIX EPOCH (1-1-1970) AND THE CURRENT TIME, DEFINED IN SECONDS.
private String calculateUnixTimeStamp()
{
long unixTime = System.currentTimeMillis() / 1000L; // the division by 1000 is performed to convert msec -> sec
String timeInSecondsAsString = Long.toString(unixTime);

return timeInSecondsAsString;
}

WSDL and java

Sometimes a HMAC error message appears after importing the Buckaroo WSDL in the java environment. In that case: please try to load the following WSDL for soap using java. The error should not show up using this WDSL.