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.

The SDK has 2 main components:

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

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];

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>

-(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;

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

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

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

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

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

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

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

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

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

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

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

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

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

-(void)onDeviceConnectionError{
   ...
}

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

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

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];

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

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

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

ExternalAccessory.framework 
CoreBluetooth.framework

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

[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);

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.

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

[terminal processSale:sale];

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");
}

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.

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.

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];
}

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 is used for every request that requires user authentication

• Refunds
• Reporting of Transactions
• Updating Terminal Settings

Steps to retrieve authentication token from the server

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>

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.

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]];
}

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.

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.