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

REST

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.

SOAP

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

Request

Response

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 and stored the new TerminalAccessToken.