Ingenico Direct Support Site

Results for

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

1. Get started

Security lies at our heart, so we make it really easy for you to process transactions safely. To make sure that no-one but you can use your integration, our platform uses security codes linked to your PSPID.

The so-called API Key and API Secret provide a unique signature to the traffic between your system and our platform. You can define these for each of your PSPIDs in your Back Office. Any server-to-server request from your system to our platform (via your PSPID) needs to contain both the API Key and API Secret. Our platform tries to match the codes we receive from you with the ones configured in your PSPID.

Our SDKs offer a simple solution for this mechanism, requiring only few lines of coding. If you wish to use your own software, manual implementation is also possible.
Read more to learn how this works and what you need to do.

2. Configure API key and API secret

To configure the API Key and API Secret in your PSPID, follow these steps:

  1. Login to the Back Office. Go to Configuration > Technical information > Ingenico Direct settings > Direct API Key
  2. If you have not configured anything yet, the screen shows “No api credential found”. To create both API Key and API Secret click on “GENERATE”
    BO_noAPIfound.png
    The image shows the Back Office message "No api credential found"

  3. The screen now shows both codes in the table in the “Key” / “Secret” column respectively
    BO_APIcredentials.png
    The image shows the information available in the "Ingenico Direct settings" Back Office tab

    Make sure to save the API Secret in your system right away, as it will not be visible in the Back Office anymore once you access this menu anew. However, you can look up the API Key anytime
Key Version date Expiration date Status
The current key configured in this PSPID The date when the Key/Secret pair was created The date when the Key/Secret pair will expire. Default time of permanency is five years The current status of the API key/secret pair
  • "Active": usable until the date as defined in column “Expiration date”
  • "Expiring": expires after the date as defined in column “Expiration date”

If you wish to use a new API Key and API Secret, follow these steps

  1. Select a period from the drop down menu “leave valid for X hour(s)”. Click on the “RENEW” button. The currenly used API Key/Secret pair will expire after the date as defined in “Expiration date”
  2. At the same time, a new API Key/Secret appears in the first line of the table. Make sure to save the API Secret in your system, as it will not be visible in the Back Office anymore once you access this menu anew
  3. To force an immediate expiration of the expiring API Key/Secret, click on “EXPIRE”. Our platform removes the respective API Key/Secret from the table and our platform, making it unusable for requests
Do not click on on “EXPIRE” if you have only one API Key/Secret at the time, as this will make them unusable instantly. Make sure to create a new API Key/Secret pair first before you force the expiration of the currently used pair.

3. Use API key and API secret with SDKs

Once you have set up your API Key/Secret in your Back Office, you can use them for requests you send to our platform. Our SDKs make it really easy to do so.

Have a look at the this code sample that demonstrates how to add them in a standard Hosted Checkout Page request:


using Ingenico.Direct.Sdk.Domain;
…

private IClient client;
private CreateHostedCheckoutRequest createHostedCheckoutRequest;
private CommunicatorConfiguration clientCommunicator;

private string yourAPIkey;
private string yourAPIsecret;
private string yourPSPID;

// Initiate fields for createHostedCheckoutRequest
AmountOfMoney amount = new AmountOfMoney();
amount.Amount = 100;
amount.CurrencyCode = “EUR”;

createHostedCheckoutRequest.Order = new Order();
createHostedCheckoutRequest.Order.AmountOfMoney = amount;

yourAPIkey = "yourAPIkey";
yourAPIsecret = "yourAPIsecret";
yourPSPID = "yourPSPID"; // Initiate the communicator with our TEST/LIVE environment clientCommunicator = new CommunicatorConfiguration(); clientCommunicator.ApiEndpoint = “https://payment.preprod.direct.ingenico.com”; // Initialise the client with the apikey, apisecret and communicator client = Factory.CreateClient(yourAPIkey, yourAPIsecret, clientCommunicator.ApiEndpoint, “YourCompanyName”); // Send the request to your PSPID on our platform and receive it via an instance of CreateHostedCheckoutResponse var createHostedCheckoutResponse = await client .WithNewMerchant(yourPSPID).HostedCheckout .CreateHostedCheckout(createHostedCheckoutRequest);

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

4. Authenticate without SDKs

If you do not want use our SDKs for your integration, we also allow you to implement the API Key/Secret manually. Have a look at what you need to know and do.

Understand technical terms

Our Server API authentication mechanism uses hashes over a number of headers (called Signature Contents). Your secret API key is used 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 learn more here)
    • 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
  • Provide the authentication signature in the HTTP header 'Authorization'

    Authorization ="GCS ::&ltbase64 encoded HMAC signature>"
  • An account is identified based on the apiKeyId

Understand name definitions

  • authorizationType currently, always v1HMAC. Based on this value both you and we 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. Check our changelog for updates
  • apiKeyId An identifier for the secret API key you can get in the Back Office. This identifier is visible in the HTTP request and is also used to identify the correct account
  • secretApiKey A shared secret you can get in the Back Office. An apiKeyId and secretApiKey are always used together. However, the secretApiKey is never visible in the HTTP request. Use the secret as input for the HMAC algorithm
  • signed-data The concatenation of several HTTP headers. Use this concatenation as input for the HMAC
  • signature The HMAC result

Construct/Concatenate ‘signed-data’

Have a look a the technical structure of the signed-data block:

<HTTP method>
<Content-Type>
<Date>
<CanonicalizedHeaders>
<CanonicalizedResource>
  • HTTP method: e.g. GET/PUT (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 to this see here)
      • Unwrap by replacing a newline with multiple spaces by a single white space.
        Have a look at this example:

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

        becomes

        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.
        Have a look at this 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

Understand examples

Have a look at three examples of increasing size and complexity. For all of the examples, we placeholders for apiKeyId / secretApiKey. Find your apiKeyId / secretApiKey in the Back Office.

apiKeyId 5e45c937b9db33ae
secretApiKey I42Zf4pVnRdroHfuHnRiJjJ2B6+22h0yQt/R3nZR8Xg =

1. A “Minimal” example

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

Signed-data:

GET

Fri, 06 Jun 2014 13:39:43 GMT
/v1/9991/tokens/123456789

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

2. Minimal example with URI and parameter encodings

Example HTTP request:

Signed-data:

GET

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: 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

Signed-data:

DELETE
application/json
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
/v1/9991/tokens/123456789

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