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

Generating the EncryptedSecret

Merchants must generate an EncryptedSecret in order to call the RegisterTerminal() operation needed to authenticate the terminal with Platform (detailed below). The encryptedSecret will be the Terminal User’s MerchantProfileId, the terminal’s DeviceSerialNumber, and the ServiceId encrypted with the terminal BDK and EncryptionKeyId. The Secret used to generate the EncryptedSecret should be formatted as < MerchantProfileId >|< DeviceSerialNumber >|< ServiceId >.

RegisterTerminal Operation

Once the terminal has generated the EncryptedSecret, 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, the newly generated encryptedSecret, and an encryptionKeyId. If any of the parameters within the RegisterTerminal() operation is incorrect, the operation will fault and error messages saying “Terminal could not be authenticated” or “An unknown error has occurred. Details have been logged on the server” will be thrown. Should this occur, call the RegisterTerminal() operation again to reset.

     
           
               6B2866C8FD500001
               A96A5D589D
               2CF5B3A635...B7B5811032
               FFFF0079000007E0007C
           
     
 

     
          
               PHNhbWw6QXNzZXJ0a........   
          
     
 

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.

In the event there is an issue updating a refreshed token, transactions will begin erroring with the message, “Terminal could not be authenticated.” Anytime the this error is received, a RegisterTerminal() request should be tried before contacting Technical Services for support.