Authentication

Our API uses a secure authentication mechanism, keeping the data of your customers safe and the interaction between you as the merchant and Ingenico ePayments secure and reliable. This page describes the Server API authentication mechanism we use with our REST API.

Every account on our system is provided with an API Key and a Secret Key. You can have multiple API Keys active at the same time. API Keys are valid for a limited time. In the Configuration Center you can view your API Key(s) and see until when they are valid. Here you can also revoke keys you don’t use (or trust) anymore and request new ones to be created.

Below are details and examples for the Server API authentication mechanism.

This authentication mechanism is only applicable to the Server API. The Client API employs a different mechanism.

You do not have to implement the logic below as a merchant when you use one of our Server SDKs. These SDKs take care of the full process described below. We highly recommend that you use one of our Server SDKs to reduce the amount of work you have to do to integrate with GlobalCollect.

A Short specification in technical terms

In short, our Server API authentication mechanism uses hashes over a number of headers (called Signature Contents) and your secret API key to verify authenticity. The hash algorithm used is HMAC-SHA256. In the bullet list below, we provide an overview of the content of the Signature.

Name definitions we use

authorizationType currently, always v1HMAC. Based on this value both you and us know which security implementation is used. A version number is used for backward compatibility in the future. We might introduce even more secure authorization types in the future.

apiKeyId An identifier for the secret API key. The apiKeyId can be retrieved from the Configuration Center. This identifier is visible in the HTTP request and is also used to identify the correct account

secretApiKey A shared secret. The shared secret can be retrieved from the Configuration Center. An apiKeyId and secretApiKey always go hand-in-hand, the difference is that secretApiKey is never visible in the HTTP request. This secret is used as input for the HMAC algorithm

signed-data The concatenation of several HTTP headers. This concatenation is used as input for the HMAC

signature The HMAC result

How to construct or concatenate the 'signed-data'

This section gives you an overview of the technical structure of the signed-data block.

Unwrapping is done by replacing a newline with multiple spaces by a single white space. As an example:

A very long line<CR><LF> <SPACE><SPACE><SPACE><SPACE>that does not fit on a single line

Should become

A very long line that does not fit on a single line

Trim all whitespaces which exist at the start and end of the value. As an example:

<space><space><space>Some text<space><space><space>

Becomes

Some text

For each header, add the following line to the signed-data result:

"<lowercased headername>:<header value>"

Construction of the CanonicalizedResource:

This is the encoded URI path without the HTTP method and including all decoded query parameters

Examples

In this section, we provide three examples of increasing size and complexity. For all of the examples, we use this example input data from the Configuration Center. Of course, you have to use your own values here that you can also obtain from your Configuration Center login.