What's new!
Version 1.3.2
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;
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 ... }
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 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);
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.
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
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.