HMAC

HMAC stands for Hash-based Message Authentication Code. It ensures that a message is not altered during transmission. The message is encrypted using a secret key, making any change immediately detectable.

HMAC Structure: HMAC [WebsiteKey]:[Base64Hash]:[Nonce]:[TimeStamp]

Fields:

• Website key: Available in Buckaroo Plaza under My Buckaroo → Websites
• Base64Hash: Uses HMAC SHA256 signing with the Secret Key (see explanation below)
• Nonce: A unique, randomly chosen string for each request
• TimeStamp: Indicates the moment the request is posted (see time stamp description below)

🚧

Please note

The Base64 hash should be 44 characters long. If longer, it might be in hexadecimal format.

Generating the HMAC SHA256 Hash:

Concatenate the following values into one string:

• Website key (from Buckaroo Plaza) My Buckaroo -> Websites
• Request method (GET or POST)
• Request URI (omit https://) Where will the request be sent to?
• Request timestamp (seconds since 01-01-1970 UTC)
• Nonce (unique string for each request)
• Request content string (MD5 hash of raw data converted to Base64)
• Secret Key (from Buckaroo Plaza under Settings → Secret Key)

🚧

Please note

The Base64-string must contain 24 characters. If there are more than 24 characters, the Base64 string will probably be calculated using the MD5-hash in hexadecimal format

Debugging

Use the Buckaroo Authentication Debugger to compare your calculated HMAC with the expected result. The debugger provides a step-by-step breakdown of the calculation on the right side of the screen.

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 details how to calculate and verify message signatures, ensuring messages are sent by Buckaroo and arrive unaltered.

Java implementation

This section lists some important considerations when implementing Buckaroo Payment solutions in Java.

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 built up.

Timestamp

Java developers should note the timestamp calculation specifics. Ensure the timestamp is in seconds, not milliseconds. The following code can be used to go from milliseconds to seconds:

// 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;
}

📘

Note

To consult how Timestamp calculation is build up in Java, visit TecAdmin's guide.

WSDL and Java

Sometimes an 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.