Authentication

Our API uses a secure authentication mechanism, keeping the data of your customers safe and the interaction between you as the merchant and Worldline 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.

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.

• MAC algorithm: HMAC-SHA256

  (input: <signature-contents> & <secretApiKey>)

• Signature contents:
  • HTTP method (GET/PUT/POST/DELETE)
  • Content-Type (application/json)
  • Date (default HTTP header, for details see https://tools.ietf.org/html/rfc2616#section-3.3)
  • CanonicalizedHeaders (custom headers specific for Worldline like X-GCS-ClientMetaInfo)
  • CanonicalizedResource (URI + query parameters)
• Each item in the signature content is followed by a new line (Line Feed), including the last item.
• Authentication signature is provided in the HTTP header 'Authorization'

  Authorization ="GCS <authorizationType>:<apiKeyId>:<base64 encoded HMAC signature>"

• An account is identified based on the apiKeyId

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.

Structure:

• Optional HTTP headers can be left empty. However, the new-line character remains intact
• HTTP method: e.g. GET/PUT but always in uppercase
• Construction of the CanonicalizedHeaders:
  • Collect all HTTP headers that start with 'X-GCS'
  • Lowercase each header-name. As an example, 'X-GCS-ClientMetaInfo' should be converted to 'x-gcs-clientmetainfo'
  • Alphabetically sort the headers
  • For the header value:
    • If the value is wrapped over multiple lines, unwrap each line (for details on how this is achieved in a formal way, see http://tools.ietf.org/html/rfc2616#section-4.2)
    • 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.

1. A “Minimal” example

HTTP request for our Server API method 'Get Token':

• GET /v1/9991/tokens/123456789 HTTP/1.1
• Host: eu.api-ingenico.com
• Date: Fri, 06 Jun 2014 13:39:43 GMT

2. Minimal example with URI and parameter encodings

Example HTTP request:

• GET /v1/consumer/ANDR%C3%89E/?q=na%20me HTTP/1.1
• Host: eu.api-ingenico.com
• Date: Fri, 06 Jun 2014 13:39:43 GMT

3. Full example with X-GCS headers

HTTP request for our Server API method 'Delete Token':

• DELETE /v1/9991/tokens/123456789 HTTP/1.1
• Host: eu.api-ingenico.com
• Content-Type: application/json
• Date: Fri, 06 Jun 2014 13:39:43 GMT
• X-GCS-ClientMetaInfo: value (could be a base64 encoded string in this case)
• X-GCS-ServerMetaInfo: value (could be a base64 encoded string in this case)
• X-GCS-CustomerHeader: some other data