EMV documentation for GoChip EMV. Easy integration to get you started.

What's new!

Version 1.3.2

  • Updated Nomad and Walker libraries to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Updated Nomad library to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Updated Nomad libraries to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements

Introduction

The CoChip SDK is an easy to use library that handles communication with the PayConex Plus payment gateway. The SDK wraps a REST interface to the PayConex Plus gateway but also implements the client side security, making it even easier to connect.

Bellow are the plugins that has already been integrated into the PayConex Plus payment gateway, which allows a very simple interface for doing transactions.

Download

Download the SDK

The SDK has 2 main components:

  • CoChip SDK

  • (Optional) Plugins

    If you are using one (or more) of the following devices you can add the corresponding plugin.

Download the Sample App

The Sample app shows how to implement CoChip SDK in your own app.

Download Sample App

Getting Started

Installation

Installation is as easy as adding the CoChip SDK to your project. The steps for iOS are as follows:

Step 1 - Copy the libcore-sdk.a to your project folder.

Step 2 - Using Xcode, select your project, navigate to Build Phases, open Link Binary with Libraries and include libcore-sdk.a in your project.

Step 3 - Add payconfig.xml into your xcode project.

Step 4 - Using Xcode, select your project, navigate into your Xcode Build Settings and make sure Other Linker Flags is set to -ObjC.

The payconfig.xml contains URL's used to access the server.

Please make sure to add the file into your project.

Demo mode should be used for development, which will use demo Host defined in payconfig.xml. To enable demo mode.

[terminal setMode:DEMO];

To switch back to LIVE mode.

[terminal setMode:LIVE];

Core API Listener

The application needs to implement the Core API Listener to interact with the SDK. On iOS this makes the most sense in a ViewController as follows:

@interface ViewController : UIViewController <CoreAPIListener>
List of CoreApiListener interface methods.
-(void)onMessage:(CoreMessage)message;
-(void)onSaleResponse:(id)sale;
-(void)onRefundResponse:(id)refund;
-(void)onTransactionListResponse:(CoreTransactions*)transaction;
-(void)onLoginUrlRetrieved:(NSString *)url;
-(void)onSignatureRequired:(CoreSignature*)signature;
-(void)onError:(CoreError) error withDescription:(NSString*) message;
-(void)onDeviceError:(CoreDeviceError) deviceError withDescription:(NSString*) message;
-(void)onSettingsRetrieved:(CoreSettings*)settings;
-(void)onDeviceConnected:(DeviceEnum)type withDeviceInfo:(NSDictionary*) deviceInfo;
-(void)onDeviceDisconnected:(DeviceEnum)type;
-(void)onSelectApplication:(NSArray*)applications;
-(void)onSelectBTDevice:(NSArray*)devices;
-(void)onDeviceConnectionError;
-(void)onReversalRetrieved:(CoreResponse*)reversalResponse;
-(void)onDeviceInfoReturned:(NSDictionary*)deviceInfo;

onMessage

Contains message coming from the SDK while processing the transaction.

- (void)onMessage:(CoreMessage)message{
   ...
}

onSaleResponse

Fires after transaction has been processed succesfully. Contains transaction response object from the server.

- (void)onSaleResponse:(id)sale{
   CoreSaleResponsecardRequest = sale;
   NSStringname = cardRequest.cardHolderName;
   NSStringtype = cardRequest.cardType;
   ...
}

onRefundResponse

Fires after refund has been processed succesfully. Contains refund response object from the server.

- (void)onRefundResponse:(id)refund{
   CoreRefundResponse refundResponse = refund;
   NSStringname = refundResponse.cardHolderName;
   NSStringtype = refundResponse.cardType;
   ...
}

onTransactionListResponse

Returns CoreTransactions object which consists of the list with the last 10 transactions in response to getTransactions method.

- (void)onTransactionListResponse:(CoreTransactions*)transaction{
   NSMutableArray *finalArray = transaction.transactionSummary;
   for (int i=0; i<[finalArray count] ; i++) {
      ...
   }
}

onLoginUrlRetrieved

Returns URL which needs to be used to sign in into SelfCare System in response to requestSecuredUrl method.

- (void)onLoginUrlRetrieved:(NSString *)url{
   // open URL in a browser
   [[UIApplication sharedApplication] openURL:[NSURL URLWithString:url]];
}

onSignatureRequired

Fires when signature is required for the transaction to be processed.

- (void)onSignatureRequired:(CoreSignature*)signature{
   //create canvas to draw a signature and pass the signature object
   _drawingCanvas.signature = signature;
   [_drawingCanvas submitSignature];
   ...
 
}

onError

This method is triggered after error has occured in the SDK.

- (void)onError:(CoreErrorType)error{
   ...
}

onDeviceError

This method is triggered when there is an error coming from the device.

-(void)onDeviceError:(CoreDeviceError) deviceError withDescription:(NSString*) message{
   ...
}

onSettingsRetrieved

Sends back terminal settings object in response to init method.

- (void)onSettingsRetrieved:(CoreSettings *)settings{
   NSMutableArraytipListArray = settings.taxListArray;
   NSMutableArraytaxListArray = settings.taxListArray;
   ...
}

onDeviceConnected

Fires when device gets connected.

-(void)onDeviceDisconnected:(DeviceEnum)type{
   ...
}

onDeviceDisconnected

Fires when device gets disconnected.

-(void)onDeviceConnected:(DeviceEnum)type withDeviceInfo:(NSDictionary*) deviceInfo{
   NSStringaddress = [deviceInfo valueForKey:@"bluetoothID"];
   NSStringsupportNFC = [deviceInfo valueForKey:@"isSupportedNfc"];
   ...
}

onSelectApplication

Fires when application selection is required by plugin.

-(void)onSelectApplication:(NSArray*)applications{
   [terminal submitApplication:0];
   ...
}

onSelectBTDevice

This method will return list of available devices.

-(void)onSelectBTDevice:(NSArray*)devices{
   ...
}

onDeviceConnectionError

Fires when there is a problem connecting to the device.

-(void)onDeviceConnectionError{
   ...
}

onReversalRetrieved

Fires after reversal has been processed succesfully.

-(void)onReversalRetrieved:(CoreResponse*)reversalResponse{
   ...
}

onDeviceInfoReturned

Device info is returned here.

-(void)onDeviceInfoReturned:(NSDictionary*)deviceInfo
   ...
}

Core SDK Initialisation

Step 1 - An instance of a Terminal must be created first. Where self is an object that implements the Core API Listener (i.e. this code snippet is done inside the ViewController)

WTPSTerminal *terminal = [WTPSTerminal alloc];
[terminal init:self];

Step 2 - Once the WTPSTerminal is created, we need to initialise it. The arguments are the terminal ID and secret. These are credentials that are required before using the SDK.

[terminal initWithConfiguration:TERMINAL_ID withSecret:SECRET];

Plugin Installation

Step 1 - Copy the appropriate plugin(s) to your project folder.

Step 2 - Using Xcode, select your project, navigate to Build Phases, open Link Binary with Libraries and include downloaded plugin(s) in your project.

Step 3 - The following frameworks need to be included in the Xcode project.

libstdc++.6.0.9.dylib

Additional Frameworks required per device

BBPosDevice

ExternalAccessory.framework 
CoreBluetooth.framework 
AudioToolbox.framework 
CoreAudio.framework 
MediaPlayer.framework 
AVFoundation.framework

Rambler

AudioToolbox.framework 
CoreAudio.framework 
MediaPlayer.framework 
AVFoundation.framework

Bluepad

ExternalAccessory.framework 
CoreBluetooth.framework

Initialise device

Now we can initialise the device using our terminal object. Where the first argument is a DeviceEnum corresponding to the device to use. The second argument is a connection type. The third argument is optional for iniatilising a bluetooth device with a pre stored bluetooth name

[terminal initDevice:BBPOSDEVICE withConnectionType:BLUETOOTH withBluetoothAddress:nil];

For devices connecting via bluetooth, onSelectBTDevice method will return list of available devices. We need to choose the device from the list to be able to connect to it.

- (void)onSelectBTDevice:(NSArray *)devices{
}

Make sure to call selectBTDevice (to connect to the device) passing the position of the device from the list.

terminal.selectBTDevice(0);

Transactions

Step 1 - Create the CoreSale object

Create a CoreSale object with the amount.

CoreSale *sale =[[CoreSale alloc] init];
sale.amount = [NSNumber numberWithDouble: 2.22];

Make sure onSettingsRetrieved method has been called before processing any transaction.

Step 2 - Send the transaction online

Call the method processSale from the Terminal object, passing the sale object as the parameter.

[terminal processSale:sale];

Step 3 - Handle the response

Depending on the status of the transaction, the response from the SDK should appear in either:

Response Handling - If all goes well the sale response object is returned in the onSaleResponse sale argument.

- (void) onSaleResponse:(id)sale{
   NSLog(@"onSaleResponse");
   NSMutableDictionary* json = [[NSMutableDictionary alloc] init];
   json = [sale getAsJsonObject:sale];
}

Error Handling - Or else the onError callback is fired with an error message.

- (void) onError:(CoreError)error withDescription:(NSString *)message{
   NSLog(@"onError");
}

Signature

There are 2 types of transactions that require a signature to be sent with the request.

  • All swiped transactions
  • Chip and signature transactions

To send a signature you need to collect the details and send them via the CoreSignature object.

Step 1 - Get an instance of CoreSignature.

The CoreSignature object is created for you and supplied via onSignatureRequired:

 - (void) onSignatureRequired:(CoreSignature*)signature{
   NSLog(@"onSignatureRequired");
   canvas._signature = signature; // Created canvas view with _signature member variable
}
startTouch(x,y)
moveTouch(x,y)
upTouch(x,y)
clearSignature()
submitSignature()

StartTouch - User has reapplied their finger.

MoveTouch - User has moved their finger.

UpTouch - The user has lifted their finger.

ClearSignature - Clears the signature.

SubmitSignature - Submits the signature.

Step 2 - Populate the CoreSignature object.

Use a canvas to call the corresponding signature touch method on the user input.

- (void) touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event
{
   UITouch *touch = [touches anyObject];
   CGPoint p = [touch locationInView:self];
   [_signature startTouch:p.x andY:p.y];
}
 
- (void) touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event
{
   UITouch *touch = [touches anyObject];
   CGPoint p = [touch locationInView:self];
   [_signature moveTouch:p.x andY:p.y];
}
 
- (void) touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event
{
   [_signature upTouch];
}

Step 3 - Send the CoreSignature object.

When the signature is completed, submitSignature method should be called to let the SDK know that the user has completed the signature.

[terminal submitSignature:signature];

Authentication Token

Authentication token is used for every request that requires user authentication

  • Refunds
  • Reporting of Transactions
  • Updating Terminal Settings

Steps to retrieve authentication token from the server

Create Scheme

In order to request the URL, custom scheme needs to be defined in your app, for the browser (used for authentication) to send back the token to your application.

After this point you will be able to redirect to the app from the browser with the valid token after successful authentication.

Step 1- Define your scheme in your info.plist file.

Step 2- Right click on your info.plist and Open As Source Code.

Step 3- Add your URL Scheme at the end of the file.

<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLName</key>
      <string>com.scheme.example</string>
      <key>CFBundleURLSchemes</key>
      <array>
             <string>schemeName</string>
      </array>
   </dict>
</array>

Transport Security needs to be set to true for the browser to redirect back to your app after the successful login.

<key>NSAppTransportSecurity</key>
<dict>
   <key>NSAllowsArbitraryLoads</key>
   <true/>   
</dict>

Request URL

Once URL scheme has been defined, use terminal object to request a secured URL which takes your URL as a paramater.

[terminal requestSecuredUrl:@"schemeName://com.scheme.example"];

Make sure the custom Scheme passed as a parameter match the one defined in your plist.

Login in the Selfcare System

onLoginUrlRetrieved callback method will be triggered with the generated URL. This URL needs to be opened in the browser to login into the selfcare system.

- (void)onLoginUrlRetrieved:(NSString *)url{
   [[UIApplication sharedApplication] openURL:[NSURL URLWithString:url]];
}

Parse Token

After successful login, the browser will redirects you back to the application with a token in the URI. The best practice is to store the token in preferences as you don't need to login every time to make authenticated requests to the server.

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
   if ([[url scheme] isEqualToString:@"schemeName"])
   {
      // parse the URL
      URLParser *parser = [[URLParser alloc] initWithURLString:[url absoluteString]];
      if([parser valueForVariable:@"authenticationToken"] != nil){ // check for errors
         NSString *token = [parser valueForVariable:@"authenticationToken"];
         [self storeToSettings:token keyToStore:@"token"]; // save token in shared preferences
         terminal.token = token;
         NSString *date = [parser valueForVariable:@"validUntilDate"]; //contains date when token expires
      }
   }
   return YES;
}

Tell terminal object about the token.

terminal.token = token;

Token is unique and valid for 48 hours as a default, after this time re-login will be required and the new token will be generated for this account.

Process authenticated requests

After this point you will be able to process refund, update terminal settings, list transactions.

Refund

CoreUnreferencedRefund *refund =[[CoreUnreferencedRefund alloc] init];
refund.amount = [NSNumber numberWithDouble: 12.3];
refund.cardCvv = @"111";
refund.cardHolderName = @"Test user";
refund.cardNumber = @"4111111111111111";
refund.cardType= @"VISA";
refund.expiryDate = @"1219";
refund.reason=@"reason";
 
[terminal processUnreferencedRefund:refund];

Refund response will be returned in onRefundResponse callback method.

List transactions

With Filter

CoreTransactionFilter *filter = [[CoreTransactionFilter alloc] init];
filter.resultsPerPage = [NSNumber numberWithInteger: 25];
filter.startDate = @"31-12-2015:12:45:30:123";
filter.endDate = @"30-01-2016:12:45:30:123";
filter.state = ALL;
[terminal getTransactions:[ NSNumber numberWithInteger:1] usingFilter:filter];

Without Filter

[terminal getTransactions];

The transactions will be returned in onTransactionListResponse callback method.

Copyright © 2017 PayConex Plus | Powered by DokuWiki
getting_started/ios/1.3.2.txt · Last modified: 2017/09/21 10:35 (external edit)