CommerceDriver™ Conversion Guide
iOS v2.0

Print Friendly, PDF & Email


In 2017, the CommerceDriver™ framework was redesigned to enhance performance and scalability by decoupling core functionality from the terminal implementation process. Separating the two functions opened up the option for EVO to certify and integrate CommerceDriver™ in markets outside the US.
This guide is designed to assist our partners in the migration process from integrations with CommerceDriver™ v1.0 to CommerceDriver™ v2.0.
You can also learn more by referring to our CommerceDriver™ Quick Start Guide for iOS and the CommerceDriver™ Technical Reference Guide, which contains class header files in Apple Doc standards.

EVO recommends reviewing the header classes for details about the associated methods and properties.

Key Changes for CommerceDriver™ v2.0


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.

Please reference the Integration section in the CommerceDriver™ Quick Start Guide for more information.


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
Note: This table covers the major classes only.


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:


- (NSURLSessionTask *)signOnWithUserName:(NSString *)username password:(NSString *)password completion:(void(^)(ESSignOnResponse *response, NSError *error))completion;
- (void)loginUser:(NSString *)username password:(NSString *)password completion:(void (^)(BOOL success, EVOIdentityLoginState state, NSString *message))completion;
Please reference the Authentication section in the CommerceDriver™ Quick Start Guide for more information regarding classes.


Check Password Expiration

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


Change Password

- (NSURLSessionTask *)changePasswordWithRequest:(ESChangePasswordRequest *)request completion:(void(^)(NSError *error))completion;
- (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:

        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;
Please reference the Terminal Setup section in the CommerceDriver™ Quick Start Guide and the Terminal Related section of the EVOCommerceDriverAPI.h documentation for additional details regarding multiple terminal support.

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:.

Please reference the Transaction Processing section of the CommerceDriver™ Quick Start Guide for additional details.

ESSwiperControllerDelegate and EVOPOSTransactionRequestDelegate Changes


- (NSDecimalNumber*)transactionAmount;


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


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


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


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


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


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


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


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


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


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


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


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


Handled internally by CommerceDriver™ v2.0.


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

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

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

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


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;
Please refer to the Terminal Management section in this document for additional details regarding connecting and disconnecting terminals.


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

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


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

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


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

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


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


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


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


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


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


Return Unlinked transactions use a separate request object, ESReturnUnlinkedRequest.


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


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


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

Transaction Detail Query


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


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

Transaction Summary Query

v2.0 – New

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