Cardknox iOS SDK is a mobile SDK targeted towards Objective C / Swift mobile application developers; it allows developers to process transactions with the Cardknox Transactions API.
Due to the necessity of the API key in this integration method, we strongly recommend reserving these features for integrations to be used solely on merchant-owned devices.
Integrate the framework file into your XCode project by referring to the technical documentation.
Choose your integration path
The SDK offers developers a couple of ways to process transactions:
In scope function
Out of scope function
Custom UI set of functions
Out of scope
Use the out of scope function when the user needs to provide their credit card information. This function displays the SDK user interface, effectively giving the control over to the SDK to acquire the sensitive credit card data from the user. The user provides the sensitive information either via a form or via a credit card device, and then the SDK processes the transaction with the gateway.
In scope
Use the in scope function when there is no need for the SDK to interact with the user through a user interface. The developer should either pass in a card number + an expiration date, or provide a tokenized card data via the xToken parameter to this function to quickly process the transaction and retrieve back the results.
Custom UI
Custom-UI integration consists of a set of functions to control the card reader device via the SDK. Currently supported card reader device is a Bluetooth VP3300 card reader. This integration path is useful when the developer has an existing UI and wishes to use a card reader device to obtain users' card sensitive information and then process the transaction with the gateway. The SDK offers a set of functions to control the card reader device. The SDK takes care of processing with the gateway and notifying the Developer’s application with the processing results.
The SDK offers the following functions: “start scanning for devices”, “stop scanning for devices”, “connect to device”, “disconnect from device”, “start transaction”, “stop transaction”.
Transaction workflows
Click here to view the transaction workflows online.
Prior to any processing, the Cardknox SDK needs to be configured with user’s metadata and the account key. These functions can be called anywhere in the application any number of times to change the metadata and/or current account key.
Transaction required parameters
Each integration path has a “process” function that accepts a “transaction parameters” object. Developers specify required values for transaction processing through that object. Same object can be used to specify optional parameters to associate with a transaction; such as invoice numbers, billing address, etc.
Transaction optional parameters
Optional transaction parameters further complement the transaction processing. All the parameters are being sent to the Gateway during processing.
Retrieving results with callbacks
The SDK can notify the application about various events during processing, such as about different card reader events during out of scope processing, or perhaps about a completed bluetooth device scan during custom UI processing.
Developers opt in to receive callbacks by subscribing to the NSNotificationCenter using one of its' methods, using a predefined value from the SDK for the “name” parameter.
The SDK uses the same “name” value to report results & various information back to subscribers.
Available callback types and integrations where they are applicable in are as follows:
Callback subscriptions & result handling
Based on your integration path choice, choose an available callback type for that integration path and subscribe with the NSNotificationCenter to receive appropriate information back from the SDK.
Transaction result callback subscription
This callback delivers a “transaction processed response” object to the subscriber.
For Swift applications using Swift UI, subscription can be made in a View as follows:
importSwiftUIstructProcessOutOfScopeView:View {// Define a Publisherlet transactionPublisher = NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDK.transactionResultSubscription_NSNotificationCenterName()))
var body: some View {VStack{}// Subscribe the Publisher with the NotificationCenter .onReceive(transactionPublisher, perform: transactionNotification) }// Define a function that accepts a Notification.// This method will be invoked when the SDK sends transaction processing resultsfunctransactionNotification(notif: Notification) {// Use the SDK's "response" object utility method to transform a Notification into a "response" objectlet response = PaymentTransactionResponse.unwrap(notif)as! PaymentTransactionResponseif response.isSuccess() {// Transaction successfully processedlet errorMessage = response.errorMessage()!let refNum = response.xRefNum()!// ... other properties ... } else {// Transaction processing resulted in an error message which can be extracted from this property:let errorMessage = response.errorMessage()!let errorCode = response.xErrorCode()!let error = response.xError()! } }}
For Swift and Objective-C applications using Storyboard, subscriptions can be made in the appropriate UIViewController lifecycle method:
importUIKitclassViewController:UIViewController {overridefuncviewWillAppear(_animated: Bool) { super.viewWillAppear(animated); let _notificationCenter = NotificationCenter.default _notificationCenter.addObserver(self, selector: #selector(transactionNotification(aNotification:)), name: Notification.Name(CardknoxSDK.transactionResultSubscription_NSNotificationCenterName()),
object:nil) }// Define a function that accepts a Notification.// This method will be invoked when the SDK sends transaction processing results@objcfunctransactionNotification(aNotification : Notification) {// Use the SDK's "response" object utility method to transform a Notification into a "response" objectlet response = PaymentTransactionResponse.unwrap(aNotification)as! PaymentTransactionResponseif response.isSuccess() {// Transaction successfully processedlet errorMessage = response.errorMessage()!let refNum = response.xRefNum()!// ... other properties ... } else {// Transaction processing resulted in an error message which can be extracted from this property:let errorMessage = response.errorMessage()!let errorCode = response.xErrorCode()!let error = response.xError()! } }}
#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"
@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{
NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter];
[notificationCenter addObserver:self
selector:@selector(transactionNotification:)
name:[CardknoxSDK transactionResultSubscription_NSNotificationCenterName]
object:nil];
}
// Define a function that accepts a Notification.
// This method will be invoked when the SDK sends transaction processing results
-(void)transactionNotification:(NSNotification*)aNotification{
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
PaymentTransactionResponse * response = [PaymentTransactionResponse unwrap:aNotification];
if(response.isSuccess)
{
// Transaction successfully processed
NSString * errorMessage = response.errorMessage;
NSString * refNum = response.xRefNum;
// ... other properties ...
NSLog([NSString stringWithFormat:@"Transaction success response! Ref num: %@", refNum]);
}
else
{
// Transaction processing resulted in an error; message can be extracted from this property:
NSString * errorMessage = response.errorMessage;
NSString * errorCode = response.xErrorCode;
NSString * error = response.xError;
NSLog([NSString stringWithFormat:@"Transaction error response - %@", errorMessage]);
}
}
@end
Card reader event callback subscription
This callback delivers information about various events happening between the application & the card reader.
For example, while out-of-scope processing the SDK can report back error events related to bluetooth device pairing, such as “bluetooth not turned on” to indicate that the mobile device wanted to use the bluetooth service to find a near card reader device but the service is unavailable, or an error such as “waiting for device bluetooth response” to indicate that the mobile device found an eligible bluetooth card reader device, and is expecting the card reader to respond back with bluetooth data. This could mean that the bluetooth button on the card reader needs to be pressed.
After an established bluetooth pair, the SDK reports back events related to obtaining the card data via the card reader. For example, a “connected” event means that the mobile device & the card reader are connected and a card data transaction can start. A “transaction started” event means that the SDK initiated a card data transaction with the card reader and the physical card can be tapped onto the card reader.
For Swift applications using Swift UI, subscription can be made in a View as follows:
importSwiftUIstructProcessOutOfScopeView:View {// Define a Publisherlet cardReaderEventPublisher = NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDK.cardreaderEventSubscription_NSNotificationCenterName()))
var body: some View {VStack{}// Subscribe the Publisher with the NotificationCenter .onReceive(cardReaderEventPublisher, perform: cardReaderEventNotification) }// Define a function that accepts a Notification.// This method will be invoked when the SDK sends card reader eventsfunccardReaderEventNotification(aNotification: Notification){// Use the SDK's "response" object utility method to transform a Notification into a "response" objectlet callback = CardknoxCardReaderCallback.unwrap(aNotification)as! CardknoxCardReaderCallback// Read the event codelet code : Int32= callback.code();// Read the event namelet name: String= callback.name()!;NSLog(String(format:"Card reader - %@", name));// Match the non-error codeif(code == CardknoxCardReaderCallbackType.connected()) {NSLog("Connected!"); }// Match the error code & get the messageif(code == CardknoxCardReaderCallbackType.error()) {let errorMessage : String= callback.message()!;NSLog(String(format:"Card reader - %@", errorMessage)); } }}
For Swift and Objective-C applications using Storyboard, subscriptions can be made in the appropriate UIViewController lifecycle method:
importUIKitclassViewController:UIViewController {overridefuncviewWillAppear(_animated: Bool) { super.viewWillAppear(animated); let _notificationCenter = NotificationCenter.default _notificationCenter.addObserver(self, selector: #selector(cardReaderEventNotification(aNotification:)), name: Notification.Name(CardknoxSDK.cardreaderEventSubscription_NSNotificationCenterName()),
object:nil) }// Define a function that accepts a Notification.// This method will be invoked when the SDK sends card reader events@objcfunccardReaderEventNotification(aNotification : Notification) {// Use the SDK's "response" object utility method to transform a Notification into a "response" objectlet callback = CardknoxCardReaderCallback.unwrap(aNotification)as! CardknoxCardReaderCallback// Read the event codelet code : Int32= callback.code();// Read the event namelet name: String= callback.name()!;NSLog(String(format:"Card reader - %@", name));// Match the non-error codeif(code == CardknoxCardReaderCallbackType.connected()) {NSLog("Connected!"); }// Match the error code & get the messageif(code == CardknoxCardReaderCallbackType.error()) {let errorMessage : String= callback.message()!;NSLog(String(format:"Card reader - %@", errorMessage)); } }}
#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"
@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{
NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter];
[notificationCenter addObserver:self
selector:@selector(cardReaderEventNotification:)
name:[CardknoxSDK cardreaderEventSubscription_NSNotificationCenterName]
object:nil];
}
// Define a function that accepts a Notification.
// This method will be invoked when the SDK sends card reader events
-(void)cardReaderEventNotification:(NSNotification*)callbackNotification{
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
CardknoxCardReaderCallback* callback = [CardknoxCardReaderCallback unwrap:callbackNotification];
// Read the event code
int code = callback.code;
// Read the event name
NSString* name = callback.name;
NSLog([NSString stringWithFormat:@"Card reader - %@", name]);
// Match the non-error code
if(code == CardknoxCardReaderCallbackType.connected){
NSLog(@"Connected");
}
// Match the error code & get the message
if(code == CardknoxCardReaderCallbackType.error){
NSString* errorMessage = callback.message;
NSLog([NSString stringWithFormat:@"Card reader - %@", errorMessage]);
}
}
@end
Card reader events
When a card reader event happens, the SDK delivers an object, of a type named similarly to “CardknoxCardReaderCallback”, back into the app.
The object encapsulates two things:
an event integer code
an event name; such as “connected”, “disconnected”, etc.
Event integer codes are enumerated in a type named similarly to "CardknoxCardReaderCallbackType".
Developer can match the received integer code value with the enumeration of interest to pinpoint a wanted event.
Scanned bluetooth device callback subscription
One of the Custom UI integration functions is a “start scanning” function. The function keeps scanning for nearby bluetooth devices until it is manually stopped with the “stop scanning” function or if it times out.
During the scanning process, for every scanned device the SDK sends a “scanned device” object that contains all the necessary metadata about the scanned device, such as the devices' display name or its internal name.
For Swift applications using Swift UI, subscription can be made in a View as follows:
importSwiftUIstructCustomUIView:View {// Track a scanned device@Stateprivatevar scannedDevice : CardknoxSDKCustomUIScannedDevice!;// Define a Publisherlet customUIscannedDeviceSubscription = NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDKCustomUI.customUI_scannedDevice_Subscription_NSNotificationCenterName()))
var body: some View {VStack{}// Subscribe the Publisher with the NotificationCenter .onReceive(customUIscannedDeviceSubscription, perform: customUIscannedDeviceSubscription)}// Define a function that accepts a Notification.// This method will be invoked when the SDK sends scanned device informationfunccustomUIscannedDeviceSubscription(aNotification: Notification){// Use the SDK's "response" object utility method to transform a Notification into a "response" object scannedDevice = CardknoxSDKCustomUIScannedDevice.from(aNotification)as! CardknoxSDKCustomUIScannedDevice;let name = scannedDevice.name();let displayName = scannedDevice.displayName();let uuid = scannedDevice.uuid(); }}
For Swift and Objective-C applications using Storyboard, subscriptions can be made in the appropriate UIViewController lifecycle method:
importUIKitclassViewController:UIViewController {// Track a scanned deviceprivatevar scannedDevice : CardknoxSDKCustomUIScannedDevice!;overridefuncviewWillAppear(_animated: Bool) { super.viewWillAppear(animated); let notificationCenter = NotificationCenter.default notificationCenter.addObserver(self, selector: #selector(customUIScannedDeviceSubscription(aNotification:)), name: Notification.Name( CardknoxSDKCustomUI.customUI_scannedDevice_Subscription_NSNotificationCenterName()), object: nil)
}// Define a function that accepts a Notification.// This method will be invoked when the SDK sends scanned device information@objcfuncscannedDeviceNotification(aNotification : Notification) {// Use the SDK's "response" object utility method to transform a Notification into a "response" objectlet scannedDevice = CardknoxSDKCustomUIScannedDevice.from(aNotification)as! CardknoxSDKCustomUIScannedDevice;let name = scannedDevice.name();let displayName = scannedDevice.displayName();let uuid = scannedDevice.uuid();// Uuid can be used to connect to the device, like this:let exampleCustomUI: CardknoxSDKCustomUI?=nil; exampleCustomUI?.connect(withUUID: uuid); }}
#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"
@interface ViewController ()
{
CardknoxSDKCustomUIScannedDevice* scannedDevice;
}
@end
@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{
NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter];
[notificationCenter addObserver:self
selector:@selector(customUIScannedDeviceSubscription:)
name:[CardknoxSDKCustomUI customUI_scannedDevice_Subscription_NSNotificationCenterName]
object:nil];
}
// Define a function that accepts a Notification.
// This method will be invoked when the SDK sends scanned device information
-(void)customUIScannedDeviceSubscription:(NSNotification*)notification{
CardknoxSDKCustomUIScannedDevice* scannedDevice = [CardknoxSDKCustomUIScannedDevice from:notification];
NSString* name = [scannedDevice name];
NSString* displayName = [scannedDevice displayName];
NSString* uuid = [scannedDevice uuid];
}
@end
Scan completed callback subscription
One of the Custom UI integration functions is a “start scanning” function. The function keeps scanning for nearby bluetooth devices until it is manually stopped with the “stop scanning” function or if it times out.
Once the scanning process ends, the SDK sends a list of scanned device objects to all subscribers. Any object in the retrieved list can be used as an argument to the “connect to device” method.
For Swift applications using Swift UI, subscription can be made in a View as follows:
importSwiftUIstructCustomUIView:View {// Track a scanned device@Stateprivatevar scannedDevice : CardknoxSDKCustomUIScannedDevice!;// Define a Publisherlet customUIscanCompletedSubscription = NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDKCustomUI.customUI_scanCompleted_Subscription_NSNotificationCenterName()))
var body: some View {VStack{}// Subscribe the Publisher with the NotificationCenter .onReceive(customUIscanCompletedSubscription, perform: customUIscanCompletedNotification(aNotification:)) }// Define a function that accepts a Notification.// This method will be invoked when the SDK stops the scanning process and sends back all scanned devicesfunccustomUIscanCompletedNotification(aNotification: Notification){let scanCompleted = CardknoxSDKCustomUIScanCompleted.from(aNotification)as! CardknoxSDKCustomUIScanCompleted;let devices : Array<Any>= scanCompleted.scannedDevices();// Example to get a first scanned VP3300 device.// All VP3300 devices have their internal name start with IDTECH prefixif(devices !=nil&& devices.count>0) {for dev in devices{let typedDevice = dev as! CardknoxSDKCustomUIScannedDevicelet name = typedDevice.name()!;if name.hasPrefix("IDTECH") {// Save the reference & use it with the "connect to device" method scannedDevice = typedDevice;break; } } } }}
For Swift applications using Storyboard, subscriptions can be made in the appropriate UIViewController lifecycle method. For Objective C applications, subscriptions can be made in the appropriate UIViewController lifecycle method:
importUIKitclassViewController:UIViewController {overridefuncviewWillAppear(_animated: Bool) { super.viewWillAppear(animated); let notificationCenter = NotificationCenter.default notificationCenter.addObserver(self, selector: #selector(customUIScanCompletedSubscription(aNotification:)), name: Notification.Name( CardknoxSDKCustomUI.customUI_scanCompleted_Subscription_NSNotificationCenterName()), object: nil)
}// Define a function that accepts a Notification.// This method will be invoked when the SDK stops the scanning process and sends back all scanned devices@objcfuncscanCompletedNotification(aNotification: Notification){let scanCompleted = CardknoxSDKCustomUIScanCompleted.from(aNotification)as! CardknoxSDKCustomUIScanCompleted;let devices : Array<Any>= scanCompleted.scannedDevices();var scannedDevice: CardknoxSDKCustomUIScannedDevice?=nil;// Example to get a first scanned VP3300 device.// All VP3300 devices have their internal name start with IDTECH prefixif(devices !=nil&& devices.count>0) {for dev in devices{let typedDevice = dev as! CardknoxSDKCustomUIScannedDevicelet name = typedDevice.name()!;if name.hasPrefix("IDTECH") {// Save the reference & use it with the "connect to device" method scannedDevice = typedDevice;break; } } } }}
#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"
@interface ViewController ()
{
}
@end
@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{
NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter];
[notificationCenter addObserver:self
selector:@selector(customUIScanCompletedSubscription:)
name:[CardknoxSDKCustomUI customUI_scanCompleted_Subscription_NSNotificationCenterName ]
object:nil];
}
// Define a function that accepts a Notification.
// This method will be invoked when the SDK stops the scanning process and sends back all scanned devices
-(void)customUIScanCompletedSubscription:(NSNotification*)notification{
CardknoxSDKCustomUIScanCompleted* scanCompleted = [CardknoxSDKCustomUIScanCompleted from:notification];
NSArray* devices = [scanCompleted scannedDevices];
CardknoxSDKCustomUIScannedDevice* scannedDevice;
// Example to get a first scanned VP3300 device.
// All VP3300 devices have their internal name start with IDTECH prefix
if (devices != nil && [devices count] > 0) {
for (id dev in devices) {
CardknoxSDKCustomUIScannedDevice * typedDevice = dev;
if([[typedDevice name] hasPrefix:@"IDTECH"])
{
// Save the reference & use it with the "connect to device" method
scannedDevice = typedDevice;
break;
}
}
}
}
@end
Out of scope integration
Out of scope processing feature allows the developer to show the Cardknox user interface for payment processing.
First, create an “out of scope” or “ui” manager kind of object. This object can create “request” objects that are capable of showing the SDK’s user interface:
let cardknoxSDKUI : CardknoxSDKUI = CardknoxSDKUI.create() as! CardknoxSDKUI;
The developer is responsible for the CardknoxSDKUI object instance. Once the object is no longer needed, the method named similar to destroy needs to be called. A good place to maintain the object are “appear” and “disappear” callbacks.
Check if the request object is in a valid state. If it is, call the method to show the UI. Otherwise, inspect the validation errors to see what is incorrect in the request object:
let request = cardknoxUI.createRequest(withParameters: prms)as! PaymentTransactionRequestUIif(request.isValid){ request.process()}else{let errors = request.validationErrors;}
The SDK’s user interface consists of two fullscreen parts - a manual entry screen and a card reader screen. Manual entry screen is also abbreviated as a “keyed” screen. The card reader screen is also abbreviated as a “swipe” screen.
Showing the SDK user interface via a Request object will either show one of the screens, or both. Which screen will be visible depends on the global SDK configuration state prior to showing the SDK user interface via a Request object.
Note that if the SDK is configured to allow access to both processing screens, one of them will be shown by default and both of them will have some kind of a visual way to navigate to the other one.
The following table shows available functions to control which screen will be visible & accessible:
The following mapping represents which screens will be available when the SDK shows its user interface:
The following mapping represents available Cardknox Transaction API commands on each user interface:
Pre processing options
Developer using the Out Of Scope integration to process using the VP3300 card reader can specify a per-request transaction timeout value. The SDK will start a transaction with the VP3300 reader, and timeout in the specified time frame if the card is not tapped, swiped or inserted in that same time frame.
Post processing options
After the out-of-scope function finishes with transaction processing, the SDK displays a popup containing a handful of information about the transaction.
SDK can be configured to auto close the user interface immediately after the transaction processing has completed; regardless if the transaction was approved or not.
In scope integration
In scope processing feature allows the developer to quickly process a payment and retrieve the response object.
First, create an “in scope” or “direct” manager kind of object. This object can create “request” objects that are capable of directly processing a transaction and returning back a “response” object.
let cardknoxDirect = CardknoxSDKDirect.create() as! CardknoxSDKDirect;
The developer is responsible for the CardknoxSDKDirect object instance. Once the object is no longer needed, the method named similar to destroy needs to be called. A good place to maintain the object are “appear” and “disappear” callbacks.
Check if the request object is in a valid state. If it is, call the method to process directly. Otherwise, inspect the validation errors to see what is incorrect in the request object:
Custom UI integration is similar to the “out of scope” integration in a way that the exact same methods that the “out of scope” is using under the hood for controlling the card reader, are exposed via the SDK for the Developer to use.
The Developer provides the user interface and orchestrates the entire flow for obtaining the card data via the card reader by calling appropriate Custom UI functions at specific times.
Available commands
Any of the following credit card commands are available for Custom UI:
First, create a “custom ui” object to get access to all the Custom UI functions. Afterwards, subscribe to all the relevant callbacks for this integration path:
transaction result callback - to receive the “response” object after the SDK has processed a transaction
card reader event callback - to be notified about various events that take place between the application & the card reader
scanned bluetooth device callback - to be notified about every new scanned bluetooth device during the “scan for devices” process
scan completed callback - to be notified about all the scanned devices once the “scan for devices” process ends
Next step is to establish a connection between the app and the card reader device. Use one of the “connect” methods on the “custom ui” to initiate a connection; such as “connect with name” or “connect with UUID”.
Device name or the UUID can be obtained with the “scan for devices” flow. Initiate the “start scanning” function call, with or without a timeout.
The scanning process stops with a call to the “stop scanning” function or when the “start scanning” function times out.
After establishing a connection with the card reader by calling one of the “connect” methods and receiving a “connected” card reader event via the NSNotificationCenter subscription, call the “start transaction” function to make the card reader ready for a card.
The SDK will report a “transaction starting” card reader event via a callback followed by the “transaction started” event if the transaction with the card reader was successfully started, otherwise an “error” card reader event is reported back. At this point the card can be tapped, swiped or inserted into the card reader. The SDK will read the card information, process a transaction & deliver the results to the application via a callback.
If no card is tapped, swiped or inserted after the transaction started - a “timeout” card reader is reported back. The default timeout value is about 10 seconds. The developer can override this value via the “transaction parameters” object.
Versioning
Developers can call the “get version” API to obtain the SDK Semantic Versioning (SemVer source)
Logging
SDK verbose logging can be enabled or disabled with a function call:
FAQ
As a Cardknox SDK user, I want to process without an internet connection. What will happen?
The SDK will return a PaymentTransactionResponse object with a special xErrorCode value -1
As a Cardknox SDK user, I’ve encountered errors during transaction processing. What response can I expect?
The PaymentTransactionRequest object will encapsulate all relevant information in respective fields; for example the xErrorCode property will return a code from the Cardknox Transaction API documentation, the xErrorMessage and xError properties can be used for a descriptive error message while the xRefNum gives back a unique ref num to follow up with the customer support