iOS SDK

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.

To start, download the SDK framework file:
Integrate the framework file into your XCode project by referring to the technical documentation.

The SDK offers developers a couple of ways to process transactions:
  • In scope function
  • Out of scope function
  • Custom UI set of functions

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.

Use the in scope function when there is no need for the SDK to interact with the user through a user interface. The developer can pass through the card number (and other parameters) to this function to quickly process a transaction and retrieve back the results.

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

Click here to view the transaction workflows online.
Download our sample applications:

Name
Required
Description
Sample data
xKey
Yes
Cardknox account key
CardknoxSupport_Test
xVersion
Yes
Gateway version
4.5.9
xSoftwareName
Yes
Name of your software
My app
xSoftwareVersion
Yes
Version number of your software
1.0.0

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.
Function
Description
setxSoftwareName
Specifies the name of your software (xSoftwareName), version number of your software (xSoftwareVersion) and the gateway version (xVersion)
​
Sample data (Swift)
​
CardknoxSDK.setxSoftwareName("Your app name", xSoftwareVersion: "Your app version, such as 1.0.0", xVersion: "4.5.9");
​
Sample data (Objective C)
​
[CardknoxSDK setxSoftwareName:@"Your app name" xSoftwareVersion:@"Your app version, such as 1.0.0" xVersion:@"4.5.9"];
setPrincipalKey
Accepts the xKey.
xKey is a Cardknox account key.
All transactions being processed after calling this function will be associated to the account that was passed in into the function.
​
Sample data (Swift)
​
CardknoxSDK.setPrincipalKey("Your xKey value")
​
Sample data (Objective C)
​
[CardknoxSDK setPrincipalKey:@"Your xKey value"];

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 additional, optional, parameters to associate with a transaction, such as invoice numbers, billing address, etc.
Name
Description
Sample data
xCommand
Cardknox transaction type
cc:sale
xAmount
Total amount of the transaction, including tax and tip, if applicable.
1.23

Some integration paths require additional parameters to process a transaction.
For example, a card number is a required parameter when processing in-scope because the in-scope integration directly sends a request to the Gateway to process a transaction and return results.
For comparison with the in-scope processing, the out-of-scope processing method is displaying the SDK user interface. In case the user interface is configured to display a manual entry form, and the card number was supplied to the “show user interface” function, the card number will be pre-filled on the user interface.
Name
Required
Description
Sample data
xCardNum
Required for in-scope,
otherwise optional
Card number
4444333322221111
xExpDate
Required for in-scope,
otherwise optional
Card expiration date.
Expected format is MMYY where MM is a month, and YY are last 2 year digits
1126 - November 2026
0122 - January 2022
xRefNum
Required for in-scope,
only if xCommand parameter is a “ref num” command, such as cc:refund, cc:void, cc:capture or similar.
Otherwise optional.
Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture.
12345678

Optional transaction parameters further complement the transaction processing. All the parameters are being sent to the Gateway during processing.
Name
Description
Sample data
xInvoice
The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPoNum
The merchant’s purchase order number for the transaction.
123485
xDescription
This is a description
This is a description
xName
The cardholder’s name.
John Doe
xBillFirstName
The customer’s first name for their billing profile.
John
xBillLastName
The customer’s last/family name for their billing profile.
Doe
xBillCompany
The customer’s company name for their billing profile.
Acme
xBillStreet
The customer’s street address for their billing profile.
123 Any Street
xBillStreet2
The customer’s second street address for their billing profile.
123 Any Street
xBillCity
The customer’s city for their billing profile.
Anytown
xBillState
The customer’s state for their billing profile.
NY
xBillZip
The customer’s zip code for their billing profile.
12345
xBillCountry
The customer’s phone number for their billing profile.
USA
xBillPhone
The customer’s phone number for their billing profile.
8005551212
xShipFirstName
The customer’s last/family name for their shipping profile.
John
xShipLastName
The customer’s last/family name for their shipping profile.
Doe
xShipCompany
The customer’s company name for their shipping profile.
Acme
xShipStreet
The customer’s street address for their shipping profile.
123 Any Street
xShipStreet2
The customer’s second street address for their shipping profile.
123 Any Street
xShipCity
The customer’s city for their shipping profile.
Anytown
xShipState
The customer’s state for their shipping profile.
NY
xShipZip
The customer’s zip code for their shipping profile.
12345
xShipCountry
The customer’s country for their shipping profile.
USA
xShipPhone
The customer’s phone number for their shipping profile.
1113333444
xCustom01
Custom field 1. Use this for any additional data
​
xCustom02
Custom field 2. Use this for any additional data
​
xCustom03
Custom field 3. Use this for any additional data
​
xAuthCode
xAuthCode is a verification number provided by the issuing bank to be used with the cc:postauth command.
​
xAllowDuplicate
By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
False
xCustReceipt
True/False value indicating if the email address specified in xEmail should receive a receipt containing the transaction details.
False
xEmail
The customer’s email address.

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 type
Description
Available in integration
Transaction result
The SDK processes a payment with the Gateway and delivers an object containing all processed transaction details.
Out of scope
Custom UI
Card reader event
The SDK keeps informing the subscribers about various events taking place between the application and the card reader device; such as “connected”, “disconnected”, “transaction started”, “on bluetooth disabled error”, etc.
Out of scope
Custom UI
Scanned bluetooth device
Trigger a bluetooth device scanning process with the “start scanning” function.
During the scanning process, the SDK keeps informing subscribers with objects that encapsulate all the information about each newly discovered Bluetooth device.
The SDK expects one of the objects as an argument in the “connect to device” function.
Custom UI
Scan completed
Trigger a bluetooth device scanning process with the “start scanning” function.
Stop the process with a “stop scanning” function.
Once the scanning process is stopped, the SDK reports back a list of all scanned bluetooth devices.
The SDK expects one of the objects as an argument in the “connect to device” function.
Custom UI

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.

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:
import SwiftUI
​
struct ProcessOutOfScopeView: View
{
// Define a Publisher
let 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 results
func transactionNotification(notif: Notification) {
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
let response = PaymentTransactionResponse.unwrap(notif) as! PaymentTransactionResponse
if response.isSuccess()
{
// Transaction successfully processed
let 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:
Swift
Objective-C
import UIKit
​
class ViewController: UIViewController {
​
override func viewWillAppear(_ 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
@objc func transactionNotification(aNotification : Notification) {
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
let response = PaymentTransactionResponse.unwrap(aNotification) as! PaymentTransactionResponse
​
if response.isSuccess()
{
// Transaction successfully processed
let 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

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:
import SwiftUI
​
struct ProcessOutOfScopeView: View
{
// Define a Publisher
let 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 events
func cardReaderEventNotification(aNotification: Notification){
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
let callback = CardknoxCardReaderCallback.unwrap(aNotification) as! CardknoxCardReaderCallback
// Read the event code
let code : Int32 = callback.code();
// Read the event name
let name: String = callback.name()!;
NSLog(String(format: "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())
{
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:
Swift
Objective-C
import UIKit
​
class ViewController: UIViewController {
​
override func viewWillAppear(_ 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
@objc func cardReaderEventNotification(aNotification : Notification) {
// Use the SDK's "response" object utility method to transform a Notification into a "response" object
let callback = CardknoxCardReaderCallback.unwrap(aNotification) as! CardknoxCardReaderCallback
// Read the event code
let code : Int32 = callback.code();
// Read the event name
let name: String = callback.name()!;
NSLog(String(format: "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())
{
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

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:
import SwiftUI
​
struct ProcessOutOfScopeView: View
{
// Track a scanned device
@State private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
// Define a Publisher
let scannedDevicePublisher =
NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDKCustomUI.customUI_scannedDevice_Subscription_NSNotificationCenterName()))
var body: some View
{
VStack{}
// Subscribe the Publisher with the NotificationCenter
.onReceive(scannedDevicePublisher, perform: scannedDeviceNotification)
}
// Define a function that accepts a Notification.
// This method will be invoked when the SDK sends scanned device information
func scannedDeviceNotification(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();
}
}
For Swift and Objective-C applications using Storyboard, subscriptions can be made in the appropriate UIViewController lifecycle method:
Swift
Objective-C
import UIKit
​
class ViewController: UIViewController {
// Track a scanned device
private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated);
let _notificationCenter = NotificationCenter.default
_notificationCenter.addObserver(self,
selector: #selector(scannedDeviceNotification(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
@objc func scannedDeviceNotification(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();
}
}
#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(scannedDeviceNotification:)
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)scannedDeviceNotification:(NSNotification*)notification{
scannedDevice = [CardknoxSDKCustomUIScannedDevice from:notification];
NSString* name = [scannedDevice name];
NSString* displayName = [scannedDevice displayName];
}
​
@end

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:
import SwiftUI
​
struct ProcessOutOfScopeView: View
{
// Track a scanned device
@State private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
// Define a Publisher
let scanCompletedPublisher =
NotificationCenter.default.publisher(for: NSNotification.Name(CardknoxSDKCustomUI.customUI_scanCompleted_Subscription_NSNotificationCenterName()))
var body: some View
{
VStack{}
// Subscribe the Publisher with the NotificationCenter
.onReceive(scanCompletedPublisher, perform: scanCompletedNotification)
}
// 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
func scanCompletedNotification(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 prefix
if(devices != nil && devices.count > 0)
{
for dev in devices{
let typedDevice = dev as! CardknoxSDKCustomUIScannedDevice
let 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:
Swift
Objective-C
import UIKit
​
class ViewController: UIViewController {
// Track a scanned device
private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated);
let _notificationCenter = NotificationCenter.default
_notificationCenter.addObserver(self,
selector: #selector(scanCompletedNotification(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
@objc func scanCompletedNotification(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 prefix
if(devices != nil && devices.count > 0)
{
for dev in devices{
let typedDevice = dev as! CardknoxSDKCustomUIScannedDevice
let 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 ()
{
CardknoxSDKCustomUIScannedDevice* scannedDevice;
}
@end
​
@implementation ViewController
​
-(void)viewWillAppear:(BOOL)animated
{
NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter];
[notificationCenter addObserver:self
selector:@selector(scanCompletedNotification:)
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)scanCompletedNotification:(NSNotification*)notification{
CardknoxSDKCustomUIScanCompleted* scanCompleted = [CardknoxSDKCustomUIScanCompleted from:notification];
NSArray* devices = [scanCompleted scannedDevices];
// 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 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;
CardknoxSDKUI* cardknoxUI = [CardknoxSDKUI create];
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.
Swift
Second Tab
import SwiftUI
struct MyView: View {
@State private var cardknoxUI : CardknoxSDKUI!;
var body: some View{
Label(title: {Text("Hello world")}, icon: {})
.onAppear(perform:onAppearFunc)
.onDisappear(perform:onDisappear)
}
func onAppearFunc(){
CardknoxSDK.setPrincipalKey("Your xKey")
CardknoxSDK.setxSoftwareName("Your app name", xSoftwareVersion: "1.0.0", xVersion: "4.5.9")
cardknoxUI = CardknoxSDKUI.create() as! CardknoxSDKUI;
}
func onDisappear(){
if(cardknoxUI != nil){
cardknoxUI.destroy();
}
cardknoxUI = nil;
}
}
#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"
​
@interface ViewController ()
{
CardknoxSDKUI* cardknoxUI;
}
@end
​
@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{
[CardknoxSDK setPrincipalKey:@"Your xKey"];
[CardknoxSDK setxSoftwareName:@"Your app name" xSoftwareVersion:@"1.0.0" xVersion:@"4.5.9"];
cardknoxUI = [CardknoxSDKUI create];
}
​
-(void)viewWillDisappear:(BOOL)animated
{
if(cardknoxUI != nil)
{
[cardknoxUI destroy];
}
cardknoxUI = nil;
}
@end
To show the user interface, create a request object that is capable of showing a user interface:
// Create the parameters object
let prms : TransactionParameters = TransactionParameters.init()
prms.xAmount = 1.23;
prms.xInvoice = "1234";
prms.xCommand = "cc:sale";
// ... other fields.
​
// Create the request object
let request = cardknoxUI.createRequest(withParameters: prms) as! PaymentTransactionRequestUI
// Create the parameters object
TransactionParameters *prms = [[TransactionParameters alloc] init];
prms.xAmount = 1.23;
prms.xInvoice = @"1234";
prms.xCommand = @"cc:sale";
// ... other fields.
​
// Create the request object
PaymentTransactionRequestUI * request = [cardknoxUI createRequestWithParameters:prms];
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! PaymentTransactionRequestUI
​
if(request.isValid){
request.process()
}
else{
let errors = request.validationErrors;
}
PaymentTransactionRequestUI * request = [cardknoxUI createRequestWithParameters:prms];
​
if([request IsValid]){
[request process];
}
else{
NSArray* 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:
Function
Description
EnableKeyedEntry
Globally configures the SDK to show the keyed screen that allows manual input interaction.
​
Sample data (Swift)
​
CardknoxSDKUI.setEnableKeyedEntry(true);
​
Sample data (Objective C)
​
CardknoxSDKUI.EnableKeyedEntry = true;
EnableDeviceInsertSwipeTap
Globally configures the SDK to show the swipe screen that allows card reader interaction.
​
Sample data (Swift)
​
CardknoxSDKUI.setEnableDeviceInsertSwipeTap(true);
​
Sample data (Objective C)
​
CardknoxSDKUI.EnableDeviceInsertSwipeTap = true;
The following mapping represents which screens will be available when the SDK shows its user interface:
EnableDeviceInsertSwipeTap
EnableKeyedEntry
Keyed screen available
Swipe screen available
false
false
Yes
No
true
false
No
Yes
false
true
Yes
No
true
true
Yes
Yes
Example of a keyed user interface. Keyed screen has a top right corner icon to navigate to the swipe screen.
Example of a swipe user interface. The swipe screen contains a button on the bottom that navigates the user to the keyed user interface.

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.
Function
Description
CloseOnProcessedTransaction
Globally configures the SDK to auto close the user interface after processing a transaction.
Default value is false.
​
Sample data (Swift)
​
CardknoxSDKUI.setCloseOnProcessedTransaction(true);
​
Sample data (Objective C)
​
CardknoxSDKUI.CloseSDKUIOnProcessedTransaction = true;
Example of a success popup
Example of an error popup

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;
CardknoxSDKDirect* cardknoxDirect = [CardknoxSDKDirect create];
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.
Swift
Objective-C
import SwiftUI
struct MyView: View {
@State private var cardknoxDirect : CardknoxSDKDirect!;
var body: some View{
Label(title: {Text("Hello world")}, icon: {})
.onAppear(perform:onAppearFunc)
.onDisappear(perform:onDisappear)
}
func onAppearFunc(){
CardknoxSDK.setPrincipalKey("Your xKey")
CardknoxSDK.setxSoftwareName("Your app name", xSoftwareVersion: "1.0.0", xVersion: "4.5.9")
cardknoxDirect = CardknoxSDKDirect.create() as! CardknoxSDKDirect;
}
func onDisappear(){
if(cardknoxDirect != nil){
cardknoxDirect.destroy();
}
cardknoxDirect = nil;
}
}