Key Changes for CommerceDriver™ v2.0

Framework

CommerceDriver™ v1.0 provided in a single framework; v2.0 divides the framework into multiple components including the Core framework, EVOCommerceDriver.framework, and frameworks for supporting terminal functionality organized by terminal manufacturer. For example, support for MagTek devices (iDynamo and uDynamo) is included in the EVOMagtekTerminals.framework. Separating the terminal framework by manufacturer allows EVO partners to limit the terminal libraries to only the models that are supported.

 

Class Names

Across all frameworks, the CommerceDriver™ class prefix has been changed from ES to EVO. The matrix below shows the v1.0 class and the v2.0 equivalent:

v1.0 Class	v2.0 Class
ESConfiguration	EVOPlatformConfiguration
ESTransactionRequest	EVOPOSTransactionRequest
ESReturnUnlinkedRequest	EVOPOSTransactionRequest
ESSwiperController	EVOCommerceDriverAPI
ESSwiperControllerDelegate	EVOPOSTransactionRequestDelegate
ESSwiperDelegate	EVOPOSTransactionRequestDelegate
ESBankcardTransactionResponse	EVOTransactionResponse

 

EVOCommerceDriverAPI class

EVOCommerceDriverAPI continues to be the main entry point for CommerceDriver™. Most activities performed in v2.0 require this object. Please reference the documentation in the EVOCommerceDriverAPI.h file for details about the new functionality provided in this class.

The sections below contain the most commonly used methods in v1.0 and in the new v2.0 method:

Authenticate

v1.0

- (NSURLSessionTask *)signOnWithUserName:(NSString *)username password:(NSString *)password completion:(void(^)(ESSignOnResponse *response, NSError *error))completion;

v2.0

- (void)loginUser:(NSString *)username password:(NSString *)password completion:(void (^)(BOOL success, EVOIdentityLoginState state, NSString *message))completion;

 

Check Password Expiration

v1.0

- (NSURLSessionTask *)getPasswordExpirationDateForUser:(NSString *)username password:(NSString *)password completion:(void(^)(NSDate *date, NSError *error))completion;

v2.0

 - (void)getPasswordDaysRemainingForUsername:(NSString *)username password:(NSString *)password completion:(void (^)(NSInteger daysRemaining))completion;

 

Change Password

v1.0

- (NSURLSessionTask *)changePasswordWithRequest:(ESChangePasswordRequest *)request completion:(void(^)(NSError *error))completion;

v2.0

- (void)changePasswordForUsername:(NSString *)username oldPassword:(NSString *)oldPassword newPassword:(NSString *)newPassword confirmPassword:(NSString *)confirmPassword completion:(void (^)(EVOChangePasswordState state, NSString *message))completion;

 

Password Reset

v2.0 (New)

//First call this method.
- (void)forgotPassword:(NSString *)username completion:(void (^)(EVOForgotPasswordState state, EVOResetPasswordData *data, NSString *message))completion;

//Then call this one.
- (void)getTemporaryPasswordForUsername:(NSString *)username resetPasswordData:(EVOResetPasswordData *)data completion:(void (^)(EVOForgotPasswordState state, EVOResetPasswordData *data, NSString *message))completion;

 

New Methods for Security Questions

//Check if a user has security questions assigned.
- (void)securityQuestionsDefined:(void (^)(BOOL isDefined))completion;

//Get a list of available security questions.
- (void)getAllSecurityQuestions:(void (^)(EVOSecurityQuestionData *data))completion;

//Get the questions assigned to a user.
- (void)getUserSecurityQuestions:(void (^)(EVOSecurityQuestionData *data))completion;

//Saves the security questions for a user.
- (void)assignQuestionsForUsername:(NSString *)username password:(NSString *)password data:(EVOSecurityQuestionData *)questionsData completion:(void (^)(EVOAssignQuestionsState state, EVOSecurityQuestionData *data, NSString *message))completion;

 

Session Expiration

In CommerceDriver™ v1.0, when a login token expires, the sessionExpiredForSwiper: method in the ESSwiperControllerDelegate is called.

In v2.0, the delegate method is replaced with an in-app notification.

To Listen for the notification:

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onPlatformEventInvalidSession:) name:EVOPlatformEventSessionInvalid object:nil];

A sample onPlatformEventInvalidSession: method:

    -(void)onPlatformEventInvalidSession:(NSNotification*)notification{
        NSLog(@"Invalid Session.");
        [[NSNotificationCenter defaultCenter] removeObserver:self name:EVOPlatformEventSessionInvalid object:nil];
        
        //Perform UI updates

        //Show a popup dialog.
        UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Session Expired" message:@"Your session has expired please login with your username and password.. " preferredStyle:UIAlertControllerStyleAlert];
        
];
        
        [self presentViewController:alert animated:YES completion:nil];
        
    }

Terminal Management

Methods for Supporting Multiple Devices

v1.0 – class ESSwiperController

//Passing the device type to specify what device to use.
- (instancetype)initWithDelegate:(id)delegate loggingEnabled:(BOOL)enabled useDevice:(ESDeviceType)deviceType;

//Or preselect the device by calling this static method.
+ (void) selectDevice:(ESDeviceType)deviceType;

v2.0 – class EVOCommerceDriverAPI

- (void)addTerminal:(EVOTerminal *)terminal;

- (void)selectTerminal:(EVOTerminal *)terminal;

- (EVOTerminal *)selectedTerminal;

- (EVOTerminal *)terminalWithIdentifier:(NSString *)identifier;

- (void)removeTerminalWithIdentifier:(NSString *)identifier;

- (void)removeTerminal:(EVOTerminal *)terminal;

Transaction Processing

In v1.0, transaction processing is largely handled by the ESSwiperController class and delegate ESSwiperControllerDelegate.

v2.0 simplifies transaction processing by including the processTransactionRequest: method in the EVOCommerceDriverAPI class. This method manages the interactions with the device through an EVOPOSTransactionRequest object. An asynchronous transaction is performed and all process interactions are handled through the EVOPOSTransactionRequestDelegate.

The delegate is set on the EVOPOSTransactionRequest delegate property. Set this property before calling processTransactionRequest:.

ESSwiperControllerDelegate and EVOPOSTransactionRequestDelegate Changes

v1.0

- (NSDecimalNumber*)transactionAmount;

v2.0

Set the transaction amount in the EVOPOSTransactionRequest before starting the transaction.

---

v1.0

- (ESTransactionRequest*)transactionRequestForSwiper:(ESSwiper*)swiper;

v2.0

An EVOPOSTransactionRequest is passed to the processTransactionRequest: method of EVOCommerceDriverAPI.

---

v1.0

- (void)swiper:(ESSwiper *)swiper didFinishMSRTransactionWithResponse:(ESBankcardTransactionResponse*)transactionResponse tender:(id)tender completion:(void (^)())completion;

v2.0

-(void)request:(EVOPOSTransactionRequest *)request completedWithResponse:(EVOTransactionResponse *)response;

---

v1.0

- (void)swiper:(ESSwiper *)swiper didFailWithError:(NSError *)error completion:(void (^)())completion;

v2.0

-(void)request:(EVOPOSTransactionRequest *)request failedToStartWithErrors:(NSDictionary *)errors ;

---

v1.0

-(void)sessionExpiredForSwiper:(ESSwiper *)swiper;

v2.0

Please refer to the Session Expiration section in this document for v2.0 replacement details.

---

v1.0

- (void)swiper:(ESSwiperController *)swiper didFinishEMVTransactionWithResult:(ESEMVTransactionResult)result response:(ESBankcardTransactionResponse*)transactionResponse tender:(id)tender completion:(void (^)())completion;

v2.0

-(void)request:(EVOPOSTransactionRequest *)request completedWithResponse:(EVOTransactionResponse *)response;

---

v1.0

- (void)swiper:(ESSwiperController *)swiper requiresRetryWithResult:(ESEMVTransactionResult)result fallbackSupported:(BOOL)fallbackSupported completion:(void(^)())completion;

v2.0

Handled internally by CommerceDriver™ v2.0.

---

v1.0

- (void)willConnectSwiper:(ESSwiper *)swiper;

- (void)didConnectSwiper:(ESSwiper *)swiper;

- (void)didFailToConnectSwiper:(ESSwiper *)swiper;

- (void)didDisconnectSwiper:(ESSwiper *)swiper;

v2.0

If an issue occurs connecting a terminal at the start of a transaction, the request:failedToStartWithErrors: delegate method call is presented.

To Check the connection to the terminal:

• Call the EVOCommerceDriverAPI method.

- (void)checkTerminalConnection:(void (^)(EVOTerminalConnectionStatus terminalStatus))completion;

---

v1.0

- (void)swiperDidStartMSR:(ESSwiper *)swiper;

- (void)swiperDidStartEMV:(ESSwiperController*)swiper;

v2.0

This method is used to send general status updates. For example, the start of an MSR transaction.

-(void)request:(EVOPOSTransactionRequest *)request statusUpdate:(NSString *)status;

---

v1.0

- (BOOL)useReturnTransactionForMSRSwiper:(ESSwiper *)swiper;

- (ESReturnUnlinkedRequest*)returnTransactionRequestForRefundTransactionFromSwiper:(ESSwiper*)swiper;

v2.0

The EVOPOSTransactionRequest is passed to the processTransactionRequest: method of EVOCommerceDriverAPI. The operation property specifies the transaction type, such as return or void.

---

v1.0

- (BOOL)overrideICCardSwipeFromSwiper:(ESSwiperController*)swiper;

v2.0

An ICC (Integrated Circuit ‘Chip’ Card) cannot be explicitly overridden. CommerceDriver™ v2.0 contains this internal logic.

---

v1.0

- (ESEMVTransactionType)transactionTypeForEMVSwiper:(ESSwiperController*)swiper;

v2.0

Removed from CommerceDriver™ v2.0.

---

 

New Delegate Methods

CommerceDriver™ v2.0 contains new delegate methods you need to implement in your EVOPOSTransactionRequestDelegate. Please refer to the Transaction Processing section in the CommerceDriver™ Quick Start Guide, as well as the documentation in the EVOPOSTransactionRequestDelegate.h file.
 

The Delegate Methods

/** When using a terminal without a display, this method is call so you can update your UI to instruct the user to swipe or insert their card. */
-(void)request:(EVOPOSTransactionRequest *)request cardReaderStatusUpdate:(EVOCardReaderState)status;

/** Called when a UI must be presented to the card holder to select the EMV application. */
-(void)request:(EVOPOSTransactionRequest *)request selectApplication:(NSArray *)applicationList completion:(void(^)(int arrayIndex))completion;

/** On terminals without a display, this delegate method is called when there is a problem reading an EMV card and the card reader needs to restart. */
-(void)request:(EVOPOSTransactionRequest *)request confirmCardRemoved:(void(^)())completion;

/** On terminals without a display, the amount confirmation must happen on the POS. */
-(void)request:(EVOPOSTransactionRequest *)request confirmTransactionAmount:(NSDecimalNumber *)amount completion:(void(^)(BOOL amountConfirmed))completion;

/** Called when signature validation is required. */
-(void)getSignatureForRequest:(EVOPOSTransactionRequest *)request withResponse:(EVOTransactionResponse *)response completion:(void(^)(BOOL signatureAccepted))completion;

Optional methods also provided:

/** Sends the name, expiration date, and masked PAN for display. */
-(void)request:(EVOPOSTransactionRequest *)request didReceivedCardData:(EVOCardReadData *)cardData;

/** Optional method to notify the receiver a duplicate transaction has been detected. */
-(void)request:(EVOPOSTransactionRequest *)request overrideDuplicate:(void(^)(BOOL processTransaction))completion;

Processing Return Unlinked

v1.0

Return Unlinked transactions use a separate request object, ESReturnUnlinkedRequest.

v2.0

Create an instance of EVOPOSTransactionRequest using the factory method below and pass EVOPOSOperationReturnUnlinked for the Operation parameter.

+ (instancetype)createTerminalRequestWithOperation:(EVOPOSOperation)operation amount:(NSDecimalNumber *)amount employeeId:(NSString *)employeeId laneId:(NSString *)laneId orderNumber:(NSString *)orderNumber reference:(NSString *)reference tipAmount:(NSDecimalNumber *)tipAmount cashbackAmount:(NSDecimalNumber *)cashbackAmount overrideApDupe:(BOOL)overrideApDupe;

Querying for Transactions

The methods for transaction queries remain in the EVOCommerceDriverAPI class, but the names and signatures of the methods have changed.

Transaction Family Query

v1.0

- (NSURLSessionTask *)queryTransactionFamilies:(ESQueryTransactionsFamilies *)families
                                    completion:(void(^)(NSArray *transactionFamilies, NSError *error))completion;

v2.0

- (void)getTransactionFamilies:(EVOQueryTransactionsFamiliesRequest *)query completion:(void (^)(EVOTransactionsFamiliesResponse *response))completion;

Transaction Detail Query

v1.0

- (NSURLSessionTask *)queryTransactionsDetail:(ESQueryTransactionsDetail *)queryTransactionsDetail completion:(void(^)(NSArray *response, NSError *error))completion;

v2.0

- (void)getTransactionDetails:(EVOQueryTransactionsDetailRequest *)query completion:(void (^)(EVOTransactionsDetailResponse *response))completion;

Transaction Summary Query

v2.0 – New

- (void)getTransactionSummary:(EVOQueryTransactionsSummaryRequest *)query completion:(void (^)(EVOTransactionsSummaryResponse *response))completion;