Authentication

Integration Key link

Regardless of API version you will need an integration key. This key is distributed by Worldline Nordics integration team and will be unique for your integration. If you are updating an existing Host2T/Connect2T integration you will need a new key. Make sure to not use the same key for your v1 and v2 integrations. If you need a new key please contact the integration team.

API version 1.x link

This version of the API uses https with a TLS-certificate, because the certificate is self-signed, hostname verification will not be possible for a local device and will need to be disabled/overridden.

There are 2 different kinds of file extensions because various operating systems treat the files differently depending on what OS you use. Neither .cert or .pem files are platform specific and neither is the content within them. In the Code Snippets sections we have some examples on how to import the certificate on different platforms.

Certificate link

ECR-REST.crt
ECR-REST.pem

API version 2.x link

To make the implementation easier and to have less variance between platforms we’ve removed the self-signed TLS certificate and replaced it with plain HTTP with a content hash.

Just like for v1 you supply an integration key with your requests, this can be considered the username of your application.
However with v2 you also get a secret key, this can be considered to be your applications password.
Never pass the secret key along, only use it to encrypt your request and then the terminal will do the same and compare hashes.

Request link

When the client makes a call to the terminal it needs to include an Authorization Header containing 3 components.

• A String identifying the authorization method: Samport-Keyed-Hash-v1
• A timestamp of the request in ISO 8601 “Date and time in UTC” format, for example: 2024-04-04T08:06:26.123Z.
  • Make sure to use milliseconds granularity or you will not be able to query the terminal more than once per second.
  • The timestamp must not differ more than 15 minutes from the terminal time. Note that UTC+00:00 is used so daylight savings has no impact.
  • The timestamp must also not be older than the last timestamp sent to terminal.
• A Base64 encoded SHA-256 hash computed over:
  • Secret key
  • Timestamp
  • HTTP Verb, for example POST or GET
  • HTTP Path, for example /api/v2/Payments
  • HTTP Content

Authorization-Hash-Input = "$Secret-Key\n$Timestamp\n$HTTP-Verb\n$HTTP-Path\n$HTTP-Content\n$Secret-Key"
Authorization-Hash = Base64(SHA256(Authorization-Hash-Input))
 
HTTP Headers
------------
Authorization = "Samport-Keyed-Hash-v1 $Timestamp $Authorization-Hash"

Response link

The terminal will authenticate the response in a similar way, but in a Server-Authorization header, validate this header to ensure the integrity of the response:

• A String identifying the authorization method: Samport-Keyed-Hash-v1
• A timestamp:
  • From the request, if the request could be verified
  • Otherwise terminal time
• A Base64 encoded SHA-256 hash computed over:
  • Secret key
  • Timestamp
  • HTTP Verb, for example POST or GET
  • HTTP Path, for example /api/v2/Payments
  • HTTP Status code, for example 200
  • HTTP Content, make sure this is entirely unchanged, including any \n character that the JSON-payload may contain

Server-Authorization-Hash-Input = "$Secret-Key\n$Timestamp\n$HTTP-Verb\n$HTTP-Path\n$HTTP-Status-Code\n$HTTP-Content\n$Secret-Key"
Server-Authorization-Hash = Base64-Encode(SHA256(Server-Auth-Hash-Input))
  
HTTP Headers
------------
Server-Authorization = "Samport-Keyed-Hash-v1 $Timestamp $Server-Authorization-Hash"