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 the Merchant Portal. 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 the Merchant Portal.

Our Server 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.

Target most up-to-date API base URL

We encourage you to always target the most up-to-date API base URL when sending requests to our platform. Have a look at our dedicated guides for a full overview:

To allow you a smooth transition, previous API base URLs remain available until further notice.

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 > API 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 "API 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 two 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 currently 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 the Merchant Portal, you can use them for requests you send to our platform. Our Server SDKs make it really easy to do so.

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


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.worldline-solutions.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

You can use our API without the SDKs by sending requests to our endpoints directly. This requires you to follow a different authentication mechanism.

Essentially, you need

  • To hash with your API Secret over several HTTP headers (the signature contents or signed-data) you send along with your request
  • Send this hash (the signature) together with your API Key to verify the authentication

Have a look at the following chapters to understand how this works and our GET, POST and DELETE examples.

Understand authentication process

A GET/POST/DELETE request following this approach includes the following steps:

  1. Create a string-to-hash, consisting of several HTTP headers
  2. Calculate the hash using the algorithm HMAC-SHA256 with your API Secret
  3. Send the actual request to our platform, including the headers, the hash and your API Key

1. Create string-to-hash

Compose the string-to-hash the signature contents or signed-data) by following these rules:

  • Order of the headers:
    
    <HTTP method>
    <Content-Type>
    <Date>
    <CanonicalizedHeaders>
    <CanonicalizedResource>
    

  • Construction of the individual headers and their content:
    
    <lowercased header name>:<header value>
    

    Apply these conventions for the content of the following headers:
    Header Content
    <HTTP method> "GET"/"POST"/"DELETE" (always in uppercase)
    <Content-Type> Fixed value "application/json; charset=utf-8" for POST requests, an empty string for GET/DELETE)
    <Date> Standard header in RFC1123 format
    <CanonicalizedHeaders> Custom headers specific for Direct like X-GCS-ClientMetaInfo
    <CanonicalizedResource> The target URI without the HTTP method and including all decoded query parameters
  • If a header value is wrapped over multiple lines, unwrap each line as described here. Unwrap by replacing a new line or 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

  • Each
     <item> 
    is followed by a new line (line feed), including the last item

Have a look at this code sample for a CreateHostedCheckout request:


public String CreateStringToHash ()
{
	string stringToHash;

	string pspid = "YourPSPID";     
	string requestMethod = "POST";
   	string contentType = "application/json; charset=utf-8";
  	string uriResource = "/hostedcheckouts";

   	string dateTime;
        DateTime currentDateTime = DateTime.Now;
        dateTime = currentDateTime.ToLocalTime().ToString("r");

   	string endpointURL = "/v2/" + pspid + uriResource; ;

 	stringToHash = requestMethod + "\n" + contentType + "\n" + dateTime + "\n" + endpointURL + "\n";
		
	return stringToHash;
}
Although the same rules apply for either HTTP method, you need to take the differences for GET/DELETE requests into account when creating the string-to-hash (I.e. missing content type, addition of query parameters to the request URI).

Have a look at the GET example or the DELETE example in our dedicated chapter to know exactly what you need to do

2. Calculate hash

Once you have created the string-to-hash (the signature contents or signed-data), you need to hash it via the MAC algorithm HMAC-SHA256 with your API Secret.
The result of the hashing is the signature you need to provide in the authorisation header of your request.

Have a look at this code sample:

public static String CreateHash(String stringToHash, String YourApiSecret)
{
     // Convert stringToHash + key into byte array
     byte[] keyAsBytes = System.Text.UTF8Encoding.UTF8.GetBytes(YourApiSecret);
     byte[] stringToHashAsBytes = System.Text.UTF8Encoding.UTF8.GetBytes(stringToHash);  

     // Create hashing method with key 
     HMACSHA256 myhmacsha256 = new HMACSHA256(keyAsBytes);

     // Create the hash(signature) using the hashing method + key
     var signature = myhmacsha256.ComputeHash(stringToHashAsBytes);

     // Convert signature in base64 string
     var encodedSignature = Convert.ToBase64String(signature);

     return encodedSignature;
}

3. Send request

Finally, you can send your request, including

  • The headers you used for creating the string-to-hash (the signature contents or signed-data)
  • The base64-encoded hash result (the “signature”) and your API Key (which our platform uses to identify your PSPID on our account) in the HTTP header 'Authorization' according to this formula:

    Authorization = "GCS v1HMAC:" + API Key + ":" + signature
  • The JSON-encoded request body for POST requests (GET/DELETE do not require a request body)
    Have a look at this code sample:
    
    public static async Task SendRequest(String apiKey, String encodedSignature, String pspid, String endpoint, String requestMethod, String contentType, String dateTime)
    {
         HttpClient client = new HttpClient();
         client.DefaultRequestHeaders.TryAddWithoutValidation("Content-Type", contentType);
         client.DefaultRequestHeaders.Add(HttpRequestHeader.Date.ToString(), dateTime);
         client.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", "GCS v1HMAC:" + apiKey + ":" 
         + encodedSignature);
         client.DefaultRequestHeaders.Referrer = new Uri("/v2/" + pspid + endpoint, UriKind.Relative);
    
    
         if (requestMethod == "POST")
         {
              // Build and send POST request
              string requestBodyAsString = @"{
    	                                   'order': {
                                                   'amountOfMoney': {
                                                        'currencyCode': 'EUR',
    			                           'amount': 100
                                                       }
                                                  }
                                            }";
    
              JObject json = JObject.Parse(requestBodyAsString);
              HttpContent requestBody = new StringContent(json.ToString(), System.Text.UTF8Encoding.UTF8, 
              "application/json");
    
              var response = await client.PostAsync("https://payment.preprod.direct.worldline-solutions.com/v2/" + pspid + 
              endpoint, requestBody);
              return response.Content.ReadAsStringAsync().Result;
    
          }
          else if (requestMethod == "GET" || "DELETE")
          {
               var response = await client.GetAsync("https://payment.preprod.direct.worldline-solutions.com/v2/" + pspid + 
               endpoint);
               return response.Content.ReadAsStringAsync().Result;
          }
          else
          {
               return "Something went wrong";
          }
    
    }
    

Understand string-to-hash examples

As the general requirements for a GET/POST/DELETE request differ, the construction of the string-to-hash does as well.
Have a look at the following examples to learn how to implement them in your system:

1. POST request

The string-to-hash (the signature contents or signed-data) for a CreateHostedCheckout request:


POST
application/json; charset=utf-8
Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/hostedcheckouts
Mind that there is a new line (line feed) after the last header (URI resource) which you also need to consider when hashing the string

2. GET request

The string-to-hash (the signature contents or signed-data) for a GetHostedCheckout request:


GET

Wed, 02 Mar 2022 11:15:51 GMT /v2/yourPSPID/hostedcheckouts/yourHostedCheckoutID
Mind that
  • There is an empty string for Content-Type header, as GET request do not have a request body
  • There is a new line (line feed) after the last header (URI resource) 

which you also need to consider when hashing the string

3. DELETE request

The string-to-hash (the signature contents or signed-data) for a DeleteToken request:


DELETE

Wed, 02 Mar 2022 11:15:51 GMT /v2/yourPSPID/tokens/yourTokenID
Mind that
  • There is an empty string for Content-Type header, as DELETE request do not have a request body
  • There is a new line (line feed) after the last header (URI resource) 

which you also need to consider when hashing the string