Terminal Authentication

Terminal Authentication Overview

 

The new Terminal Authentication process for the EVO Snap* Platform will solve common issues related to the authentication of terminals, including eliminating the requirement for terminals to continually refresh session tokens and reducing memory requirements for terminals.

 

Acquiring the TerminalAccessToken

RegisterTerminal Operation

Terminals must call the new RegisterTerminal() operation to authenticate the terminal with the Platform and receive their first TerminalAccessToken. Calling this operation requires that the terminal pass in the serviceKey, vendorId, an encryptedSecret, and an encryptionKeyId. The encryptedSecret will be the MerchantProfileId and DeviceSerialNumber encrypted with the terminal BDK, and the encrypted string should be formatted as <MerchantProfileId>|<DeviceSerialNumber>; if any of the parameters within the RegisterTerminal() operation is incorrect, the operation will fault and an error message saying “Terminal could not be authenticated” will be thrown. Should this occur, call the RegisterTerminal() operation again to reset.

 

RegisterTerminal API Reference

RequestUrihttps://api.ciptest.local/2.1.32/REST/SIS.svc/registerTerminal/{ServiceKey}/{VendorId}
MethodPOST

Request
Set {EncryptedSecret}:{EncryptionKeyId} as the Username on the HTTP Authetication header.

Response
A new, long lived TerminalAccessToken is returned to the terminal on the RegisterTerminal() response.

RequestUrihttps://api.ciptest.local/2.1.32/SIS.svc

Request



     
           
               6B2866C8FD500001
               A96A5D589D
               2CF5B3A635...B7B5811032
               FFFF0079000007E0007C
           
     
 

Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
     <s:Body>
          <RegisterTerminalResponse xmlns="http://schemas.evosnap.com/CWS/v2.0/ServiceInformation">
               <RegisterTerminalResult>PHNhbWw6QXNzZXJ0a........   </RegisterTerminalResult>
          </RegisterTerminalResponse>
     </s:Body>
</s:Envelope> 
 

TerminalAccessToken Details

 

A new, long lived TerminalAccessToken is returned to the terminal on the RegisterTerminal() response, as well as periodically on transaction processing responses. The terminal stores this token and uses it as the session token on future transactions, eliminating the need to continually refresh session tokens. This token will be periodically updated by the Snap* Platform on transaction processing responses. Expiration time on these tokens are configurable, but default to 90 days.

 

Receiving the Updated TerminalAccessToken

During regular transaction processing, Platform goes through a series of steps to generate a new TerminalAccessToken, which is then returned on the transaction response. The terminal should always check the transaction response for an updated token and then store the token to be used as the session token on future transactions. Again, the expiration time on these tokens are configurable, but default to 90 days.

 

Auto-Refreshing the TerminalAccessToken

The TerminalAccessToken must be renewed before it reaches its 90 day expiration. By implementing an automatic process that renews the TerminalAccessToken 30 days after token-creation, various opportunities are created for the terminal to receive the renewed TerminalAccessToken before its 90-day expiration. When a TerminalAccessToken reaches day 30 of its existence, a flag is staged in the terminal database, called the RefreshToken flag, is marked as “True”, which indicates that on the next processed transaction, a new TerminalAccessToken will be created and appended to the response.

The new expiration date is then 90 days from the day the terminal received the new TerminalAccessToken. This auto-renewal process will occur repeatedly, 30 days after the terminal successfully receives and stores a new TerminalAccessToken. The RefreshToken flag will remain true in Terminal database until a transaction has been processed and the terminal has received the new TerminalAccessToken.

Note: only a transaction that contains encrypted track data will be eligible for a token refresh.