Server API version 1.0

Results for

icon-search-large No search results yet
Enter your search query above


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.

  • MAC algorithm: HMAC-SHA256
    (input: <signature-contents> & <secretApiKey>)
  • Signature contents:
    • Content-Type (application/json)
    • Date (default HTTP header, for details see
    • CanonicalizedHeaders (custom headers specific for Ingenico 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.


<HTTP method>
  • 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
      • 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 exists at the start and end of the value.
        As an example:

        <space><space><space>Some text<space><space><space>
        Some text
      • For each header, add the following line to the signed-data result:
        "<lowercased headername>:<header value>\n"
      • Construction of the CanonicalizedResource:
        • This is the encoded URI path without the HTTP method and including all decoded query parameters


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.

apiKeyId 5e45c937b9db33ae
secretApiKey I42Zf4pVnRdroHfuHnRiJjJ2B6+22h0yQt/R3nZR8Xg=

1. A “Minimal” example

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

  • GET /v1/9991/tokens/123456789 HTTP/1.1
  • Host:
  • Date: Fri, 06 Jun 2014 13:39:43 GMT

Fri, 06 Jun 2014 13:39:43 GMT

Resulting HTTP header:
Authorization="GCS v1HMAC:5e45c937b9db33ae:J5LjfSBvrQNhu7gG0gvifZt+IWNDReGCmHmBmth6ueI="

2. Minimal example with URI and parameter encodings

Example HTTP request:

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

Fri, 06 Jun 2014 13:39:43 GMT
/v1/consumer/ANDR%C3%89E/?q=na me

Resulting HTTP header:
Authorization="GCS v1HMAC:5e45c937b9db33ae:x9S2hQmLhLTbpK0YdTuYCD8TB4D+Kf60tNW0Xw5Xls0="

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:
  • 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
Fri, 06 Jun 2014 13:39:43 GMT
x-gcs-clientmetainfo:processed header value
x-gcs-customerheader:processed header value
x-gcs-servermetainfo:processed header value

Resulting HTTP header:
Authorization="GCS v1HMAC:5e45c937b9db33ae:jGWLz3ouN4klE+SkqO5gO+KkbQNM06Rric7E3dcfmqw="