The authentication of this JSON API is based on a standard HMAC Authentication implementation. See this acticle for a basic explanation of HMAC.
To authenticate your application to the API you need to set the correct Authorization Header. See below for an example for such a header.
Authorization: hmac ABCD1234:WISKbwwMbWhMRSRJc0jFtg/LIvB9vM5VWPvfVa0JnMc=:134ee2ec5c9d43d7acfae9190ec7eb83:1434973589
We are now going to break this header up in pieces. All values are seperated by a colon ":".
| Parameter | Explanation |
|---|---|
| hmac | The authentication scheme. Always "hmac". |
| ABCD1234 | Website Key: this key can be found in the Buckaroo payment plaza at https://plaza.buckaroo.nl/. Click on My Buckaroo -> Websites -> select your website in filter. Here you can find the website key. |
| WISKbwwMbWhMRSRJc0jFtg/LIvB9vM5VWPvfVa0JnMc= | A Base64 hash using HMAC SHA256 signed with your Secret Key. See this article for implementations of HMAC SHA256 is multiple languages. The HMAC SHA256 is calculated over a concatenated string (as raw data) of the following values: WebsiteKey, requestHttpMethod, requestUri, requestTimeStamp, nonce, requestContentBase64String. See the next table for more information about these values. |
| 134ee2ec5c9d43d7acfae9190ec7eb83 | Nonce: A random sequence of characters, this should differ from for each request. See this article for more information. |
| 1434973589 | Request TimeStamp: An integer of the total amount of seconds elapsed since 01-01-1970 (00:00:00:00) in UTC time. |
See below for an explanation of the values used to generate the HMAC SHA256 hash. All these parameters (except the Secret Key) should be concatenated into one string for the generation of the HMAC SHA256 hash.
| Parameter | Explanation |
|---|---|
| Website key | Website Key: this key can be found in the Buckaroo payment plaza at https://plaza.buckaroo.nl/. Click on My Buckaroo -> Websites -> select your website in filter. Here you can find the website key. |
| Request method | Usually GET or POST, always uppercase. |
| Request uri | The request uri without the protocol. First uri encoded and then to lowercase. So, for example: "https://testcheckout.buckaroo.nl/json/Transaction/Specification/ideal" would become "testcheckout.buckaroo.nl%2fjson%2ftransaction%2fspecification%2fideal" |
| Request timestamp | An integer of the total amount of seconds elapsed since 01-01-1970 (00:00:00:00) in UTC time. |
| Nonce | A random sequence of characters, this should differ from for each request. See this article for more information. |
| Request content string | Create an MD5 hash (as raw data) of the request content. Then convert this hash to a Base64 string. In case of a GET request, leave empty. |
| Secret Key | This key is used to generate the HMAC SHA256 hash. |
| Header Name | Explanation |
|---|---|
| culture | The user culture if applicable (for example: nl-NL) |
| channel | The used channel, mostly 'Web' is used. |
| software | A definition of the software used to create the request, this needs be a JSON string in the following format: {"PlatformName":"X","PlatformVersion":"1.0","ModuleSupplier":"X","ModuleName":"X","ModuleVersion":"1.0"} |
See below an example of the HMAC authentication integration in C#.
NOTE: This solution depends on the "Json.NET" Library (http://www.newtonsoft.com/json).
See below an example of the HMAC authentication integration in JavaScript.
NOTE: The Following scripts of the CryptoJs Library (http://code.google.com/p/crypto-js/) are required for this implementation of the HMAC authentication:
This module can be used like the following example