iOS - Version 1.4.7

What's new!

  • Payconfig file can now be used to include terminal ID and secret
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Payconfig file can now be used to include terminal ID and secret
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Payconfig file can now be used to include terminal ID and secret
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for quick-chip using IDTech (Augusta) device
  • Payconfig file can now be used to include terminal ID and secret
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for removing old/expired CAPK's from BBPos devices
  • Various bug fixes improvements
  • Added support for reference EMV transactions
  • Added support for reference refunds
  • Added validation when user sends NULL or Empty values for Terminal ID and Secret
  • Card holder name is now being sent as part of the MSR request
  • onError message now includes error code at the start of the message

Introduction to The SDK

The CoChip SDK is a library for communicating with the PayConex Plus Payment Gateway. The SDK wraps a set of interfaces to communicate with the PayConex Plus payment gateway, with the card device reader libs and the client's side security.

For further reading, visit Understanding the SDK for an explanation on how the interaction between the components happen.

Please follow the steps int the section below to implement your solution.

If you have questions, please talk to us using the Contact link at the top (right side) of this page. We would love to help!

Download The Components

Step 01 - Download the SDK

The SDK has two main components: CoChip SDK and Plugins (Optional).


If you are using a card reader device, don't forget to select the check box for the plug-ins above before hitting the Download button. The SDK, and the chosen plugins, will be downloaded simultaneously.

Step 02 - Download the Sample App

The Sample App is a demonstration of how to use the CoChip SDK in your own app.

If you are developing your own application from scratch, we recommend that you use the Sample App to assist you in your testing. The Sample App can also help in the implementation of your own logic and provide a base for your development work.

Download Sample App

Basic Settings and Initialisation

Step 01 - SDK Installation

The installation of the SDK is as easy as adding the CoChip SDK to your project. For that you need:

I) Copy the libcore-sdk.a to your project folder.

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

III) Add payconfig.xml into your Xcode project.

IV) Using Xcode, select your project, navigate into your Xcode Build Settings and make sure the Other Linker Flags option is set to -ObjC.

The payconfig.xml file contains URLs used to access the servers, so don't forget to add it to your project, or the communication is not going to happpen.

If you want to start with the Sample App, just follow the steps of creating a new project from an existing source. Each IDE works in a different way, but when creating a new project, most offer an option to create based on an existing project or based on source files where you just have to point to a repository. This repository would be the decompressed folder of the Sample App in the last step of the previous section.

Step 02 - Implementing the CoreAPIListener

The application needs to implement the Core API Listener (CoreAPIListener) to interact with the SDK.

On iOS this makes the most sense in a ViewController, as follows:

  • @interface ViewController : UIViewController <CoreAPIListener>


For further reading on CoreAPIListener, consult the Core API Listener page at the SDK Documentation section.

Step 03 - Terminal Initialisation

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


II) Now, set the Terminal Mode, (TEST, DEV or LIVE), depending on your needs.

This is an easy one as well. All you have to do is to set the terminal mode to the right type.

The Test Mode should be used for development - It's going to make your app to use the gatewayTestUrl defined in payconfig.xml when communicating with the server. Before initiate your Terminal, enable the Test Mode:

  • [terminal setMode:TEST];


After finishing the development of your app, don't forget to change the mode again to go Live (Live Mode, that points to gatewayLiveUrl defined in payconfig.xml file).

  • [terminal setMode:LIVE];


You still have one option: the Dev Mode.

  • [terminal setMode:DEV];


The Dev Mode is used to point to gatewayDevUrl defined in payconfig.xml file. The Dev Host usually contains unreleased features.

III) Once the Terminal is created, initialize it.

The arguments are the terminal ID and secret. These are credentials required to use a Terminal using the SDK.

  • [terminal initWithConfiguration:TERMINAL_ID withSecret:SECRET];



Step 04 - Handling the Initialisation Response

Once the Terminal is initialized, it is necessary to handle all response types.

The Terminal initialization attempts to connect to the server and the response must then be verified. The SDK does that with the methods: onError and onSettingsRetrieved.

Successful Response

If your initialization worked properly, without problems, your application is going to receive the response at the onSettingsRetrieved method.

  • - (void)onSettingsRetrieved:(CoreSettings *)settings{
       // ...
    }


You need to use the argument returned to extract the response.

Unsuccessful Response

If anything went wrong with the initialization, your application is going to receive an error at the onError method.

  • - (void)onError:(CoreErrorType)error{
    	NSLog(@"onError");
    	// ... treatment for initialization error
    }


In the event of an error, your application can show the error text, a generic message or execute a particular action, based on the error.

Step 05 - Plugin Installation

I) Copy the appropriate plugin(s) to your project folder.

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

III) The following frameworks need to be included in the Xcode project.

libstdc++.6.0.9.dylib

IV) Additional Frameworks Required per Device, in case you are using any of the plugins.

  • 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

Step 06 - Initialize the Device

Now we can initialize the device using our Terminal.

The first argument is a DeviceEnum corresponding to the device your application is going to use. The second argument is a connection type. The third argument is optional for initializing 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. It will be possible to choose the device from the list to connect to it.

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


Call selectBTDevice (to connect to the device) to pass the position of the device from the list. The argument passed is the position of the device selected by the user from the list returned by the onSelectBTDevice above.

  • terminal.selectBTDevice(0);


For further reading on how to execute transactions, go to the Default Mode subsection or explore one of the options at the Transaction Flows section.