Authentication & security

You'll need to authenticate your requests to access any of the endpoints in the HUB API. In this guide, we'll look at how authentication works. The HUB uses an API key as an Authentication: bearer for every request made.

API key

All the HUB api's use the API key as an authentication header. Here's how to authenticate using cURL:

curl https://codebrain-ppp.nl/api/v1/guardian \
  -H "Authorization: Bearer {api_key}"

X-Signature Header

The X-Signature header is a crucial component of our REST API authentication and security system. This header is required to ensure the integrity and authenticity of the data being transmitted in POST requests. It is calculated over the entire POST body and plays a vital role in preventing data tampering and unauthorized access. Here's how to add the token to the request header using cURL:

curl https://codebrain-ppp.nl/api/v1/paymentjobs \
    -H "Authorization: Bearer {token}" \
    -H "x-signature: {signature}" \
    -H "Content-Type: application/json"
    -d '{
            "timestamp": 1694960469,
            "currency": "EUR",
            "amount": 23.9,
            "return_url": "https:\/\/demo.nl\/payment\/pppideal\/callback",
            "report_url": "https:\/\/demo.nl\/payment\/ppp\/notify",
            "payment_method": "ideal",
            "order_id": "12345",
            "order_number": "12345",
            "language": "en",
            "ip_address": "12.345.678.90"
        }'

To include the X-Signature header in a POST request:

1. Calculate the signature using the defined algorithm hmac SHA-512 and the entire POST body, using the accesstoken as a SALT.
2. Include the calculated signature in the X-Signature header of the request.
3. The server will perform a similar calculation using its shared secret and the received POST body to verify the authenticity of the request.

Webhook & configuration

When announcing the transaction the webhook is also send to the acquirer and will be processed automatically. On the iDEAL 2.0 dashboard you do need to set the API key for authentication, this is the API key of your POS. After processing the call will be forwarded to the URL you have set in the transaction request. The webhook will be send as a POST request.

Configure the webhook in the iDEAL 2.0 dashboard:

1. Navigate to https://ideal.rabobank.nl and login with your credentials.
2. Click on "Merchant data" -> "iDEAL Service data" and then scroll down to "Specific details".
3. There are 2 fields on the right that we need to fill out, these are called the "Status Notification URL" and "Notification BearerToken".
4. In field "Status Notification URL" enter your webshop URL and add /v3 to the end (example: https://webshop.nl/v3).
5. In field "Notification BearerToken" you need to enter the API key that you have also placed in the plug-in.

Using an SDK

If you use one of our official SDKs, you won't have to worry about the signature calculation and verification — fetch your API key from the HUB dashboard , and the client library will take care of the rest.