iOS SDK

Overview

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.

Getting started

To start, download the SDK framework file:

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.

Download our sample applications:

Basic parameters

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

Basic parameter functions

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

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.

Name

Description

Sample data

xCommand

Cardknox transaction type

cc:sale

Transaction optional parameters

Optional transaction parameters further complement the transaction processing. All the parameters are being sent to the Gateway during processing.

Name

Description

Sample data

VP3300TransactionTimeout

Start transaction timeout, in seconds.

Once the transaction with the VP3300 reader is started; the SDK times out if the card is not provided in the time frame specified by this timeout value.

This parameter is only applicable for SDK integrations that use a VP3300 card reader; such as CustomUI or OutOfScope integrations.

Refer to the Custom UI flow or Out Of Scope flow for samples.

xCardNum

Card number

4444333322221111

xExpDate

Card expiration date.

Expected format is MMYY where MM is a month, and YY are last 2 year digits

“1126” for (November 2026)

“0122” for “January 2022”

xToken

From Transaction API:

The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.

61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84

xRefNum

Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture.

12345678

xInvoice

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

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.

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.

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.

test@example.com

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

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:

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:

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

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:

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:

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

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.

Event name

Description

connecting

The Cardknox SDK calls into the card reader SDK to connect with the reader, in scenarios such as:

“connect to device” method in the “custom ui” integration
when it presents its own UI in “process out of scope” integration

The card reader SDK starts searching for nearby IDTech card readers & notifies the Cardknox SDK with a “connecting” event.

The Cardknox SDK raises a “connecting” callback which notifies the app.

waitingForDeviceResponse

This event is raised whenever the Cardknox SDK scans for nearby card readers. Awake readers are usually auto connected straight away.

Asleep or not, this event is always raised from the SDK to indicate that some action is required on the device.

This event is raised in the “custom ui” integration when:

a Developer calls the “start scanning” method and the underlying bluetooth adapter starts scanning
or when a Developer calls the “connect to device” method. Cardknox SDK will call the card reader SDk to “connect” and raise this event

This event is raised in the “process out of scope” integration when:

the Cardknox SDK presents its user interface; automatically starting a bluetooth scan for a nearby card reader, expecting a response back

connected

Raised when the app & the card reader establish a bluetooth connection.

Bluetooth connection is established when the Cardknox SDK scans for card readers, and card readers respond back with some bluetooth payload.

disconnected

Card reader SDK sends this event to the Cardknox SDK whenever a bluetooth card reader goes to sleep.

This event is never raised explicitly by the Cardknox SDK.

transactionStarting

Informational event.

Cardknox SDK raises this event before it places a call to the underlying card reader SDK in order to start a transaction with the card reader.

transactionStarted

Cardknox SDK attempts a “start transaction” call with the card reader SDK.

Card reader SDK successfully starts the transaction and notifies the Cardknox SDK with this event.

Cardknox SDK calls back with this event to the app.

transaction start error timeout

Cardknox SDK attempts a “start transaction” call with the card reader SDK.

The card reader never receives a card in a specified timeout frame window (about 10 seconds) and the transaction times out.

transaction start device disconnected

Cardknox SDK wants to start the transaction with a disconnected device.

transactionCancelled

Generally, this is raised whenever an error occurs at any point between starting a transaction with the reader and obtaining the card data.

See the “error” event for error examples.

The Cardknox SDK in cases of these errors preventively calls the “cancel any pending transactions” internally to clean up.

Specifically, this event is raised in the “custom ui” integration when:

a “cancel transaction” method is called & the card reader SDK cancels all pending transactions between the app & the card reader

Furthermore, this event is raised in the “process out of scope” integration when:

the Cardknox SDK’s user interface is closed; either via a pull down gesture or via a “close” UI element; to clean things up
the charge amount gets modified via UI and becomes invalid, effectively invalidating any pending transactions between the app & the card reader

scanStop

Indicates that the Cardknox SDK stopped its own bluetooth scanning.

Raised in the “custom ui” integration when:

a Developer explicitly calls the “stop scanning” method
when the “start scanning” method was called with a timeout value and the timeout expired or was cancelled / interrupted
in the “disconnect from current device” call if the “connect to device” method was called beforehand but there is no connected device to disconnect from

Raised in the “process out of scope” integration when:

the SDK shows its' UI and automatically starts scanning for nearby readers. User can explicitly stop the scanning process

scanStart

Indicates that the Cardknox SDK started a bluetooth scanning process.

Raised in the “custom ui” integration when:

the “start scanning” method was called, with or without a timeout value

Raised in the “process out of scope” integration when:

the SDK shows its' UI and automatically starts scanning for nearby readers

error

This is raised whenever an error occurs at any point between starting a transaction with the reader and obtaining the card data.

Things that might go wrong (not a complete list) are:

transaction with the card reader failed to start
emv card readings are corrupted
transaction started but the card was not tapped / swiped / inserted in time

An descriptive error message is always accompanying this 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:

import SwiftUI

struct CustomUIView: View 
{
  // Track a scanned device
  @State private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
  
  // Define a Publisher
  let 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 information
  func customUIscannedDeviceSubscription(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:

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(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
    @objc func scannedDeviceNotification(aNotification : Notification) {
        // Use the SDK's "response" object utility method to transform a Notification into a "response" object
        let 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

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 CustomUIView: View 
{
  // Track a scanned device
  @State private var scannedDevice : CardknoxSDKCustomUIScannedDevice!;
  
  // Define a Publisher
  let 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 devices
  func customUIscanCompletedNotification(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. For Objective C applications, subscriptions can be made in the appropriate UIViewController lifecycle method:

import UIKit

class ViewController: UIViewController {
    
    override func viewWillAppear(_ 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
    @objc func scanCompletedNotification(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 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 ()
{
}
@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;

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.

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

Available user interfaces

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

Yes

true

false

Yes

false

true

Yes

true

Yes

The following mapping represents available Cardknox Transaction API commands on each user interface:

Keyed

Swipe

Any Cardknox Transaction API command

Any of the following credit card commands:

cc:save
cc:credit
cc:authonly
cc:sale

Reference: https://docs.cardknox.com/api/transaction#credit-card

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.

Function/property

Description

VP3300TransactionTimeout

Start transaction value, in seconds.

Sample data (Swift)

let ui = CardknoxSDKUI.create();

let parameters : TransactionParameters = TransactionParameters.init()

parameters.vp3300TransactionTimeout = 13;

let req = cardknoxSDKUI?.createRequest(withParameters: parameters) as! PaymentTransactionRequestUI

// Enable swipe screen in the Cardknox UI

CardknoxSDKUI.setEnableDeviceInsertSwipeTap(true)

// Show Cardknox UI

req.process();

Sample data (Objective C)

CardknoxSDKUI *ui = [CardknoxSDKUI create];

TransactionParameters *parameters = [[TransactionParameters alloc] init];

parameters.VP3300TransactionTimeout = 13;

PaymentTransactionRequestUI *req = [cardknoxSDKUI createRequestWithParameters:parameters];

// Enable swipe screen in the Cardknox UI

CardknoxSDKUI.EnableDeviceInsertSwipeTap = true;

// Show Cardknox UI

[req process];

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.

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;

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;

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.

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

#import "ViewController.h"
#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"

@interface ViewController ()
{
    CardknoxSDKDirect* cardknoxDirect;
}
@end

@implementation ViewController
-(void)viewWillAppear:(BOOL)animated
{ 
    [CardknoxSDK setPrincipalKey:@"Your xKey"];
    [CardknoxSDK setxSoftwareName:@"Your app name" xSoftwareVersion:@"1.0.0" xVersion:@"4.5.9"];
    cardknoxDirect = [CardknoxSDKDirect create];
}

-(void)viewWillDisappear:(BOOL)animated
{
    if(cardknoxDirect != nil)
    {
        [cardknoxDirect destroy];
    }
    
    cardknoxDirect = nil;
}
@end

To process directly, create a request object:

// 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 = cardknoxDirect.createRequest(withParameters: prms) as! PaymentTransactionRequestDirect;

// 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
PaymentTransactionRequestDirect* request = [cardknoxDirect createRequestWithParameters:prms];ct

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:

let request = cardknoxDirect.createRequest(withParameters: prms) as! PaymentTransactionRequestDirect;

if(request.isValid){
    let response : PaymentTransactionResponse = request.process() as! PaymentTransactionResponse;
    let isSuccess = response.isSuccess();
    let errorMessage = response.errorMessage();
    let errorCode = response.xErrorCode();
    let refNum = response.xRefNum();
}
else{
    let errors = request.validationErrors;
}

PaymentTransactionRequestDirect* request = [cardknoxDirect createRequestWithParameters:prms];

if([request IsValid]){
    PaymentTransactionResponse * response = [request process];
    bool isSuccess = response.isSuccess;
    NSString * errorMessage = response.errorMessage;
    NSString * errorCode = response.xErrorCode;
    NSString * refNum = response.xRefNum;
}
else{
    NSArray* errors = request.ValidationErrors;
}

Available commands

Check (ACH) commands
- Reference: Check (ACH)
Credit Card commands
- Reference: Credit Card
EBT Food Stamp commands
- Reference: EBT Food Stamp
EBT Cash Benefits
- Reference: EBT Cash Benefits
EBT Wic
- Reference: EBT Wic
Gift Card commands
- Reference: Gift Card

Custom UI integration

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.

Function

Description

Create

Creates a “custom ui” object which can be used to call other functions.

Developer is responsible for this object. A method similar to “destroy” needs to be called when this object is no longer needed

Sample data (Swift)

let customUI = CardknoxSDKCustomUI.create() as! CardknoxSDKCustomUI;

Sample data (Objective C)

CardknoxSDKCustomUI* customUI = [CardknoxSDKCustomUI create];

Destroy

Cleans up the state from the “custom ui” object.

Sample data (Swift)

customUI.destroy();

Sample data (Objective C)

[cardknoxUI destroy];

StartScanning

Starts the “scan for nearby bluetooth devices” process.

If the timeout value is 0 or a negative number, the scanning never times out. A card reader event similar to “waiting for device response” will be raised once the scanning starts. This usually means that the user needs to press the physical button in order for the card reader device to be visible to nearby scanners.

Sample data (Swift)

customUI.startScanning(withTimeout: 0);

Sample data (Objective C)

[customUI startScanningWithTimeout:0];

StopScanning

Attempts to stop the bluetooth device scanning process.

Raises a “stop scan” card reader event.

Doesn’t do anything if scanning is not in progress.

If the method stops the scanning process, the SDK reports all scanned devices via a callback.

Sample data (Swift)

customUI.stopScanning();

Sample data (Objective C)

[customUI stopScanning];

ConnectWithName

Accepts a device name.

Configures the SDK to be ready to establish a Bluetooth connection with the nearby VP3300 device with a name equal to the provided name.

After the call:

The card reader & the app are not connected immediately but rather the SDK notifies the developer about various card reader events taking place after this method is called; such as “connecting” and “waiting for device response”
If the VP3300 devices’ bluetooth is not asleep when this method is called, the card reader auto connects to the app

Sample data (Swift)

let scannedDevice : String = nil;

customUI.connect(toDevice: scannedDevice);

Sample data (Objective C)

NSString* scannedDevice = nil;

[customUI connectToDevice:scannedDevice];

ConnectwithUUID

Accepts an UUID in a string format.

Configures the SDK to be ready to establish a Bluetooth connection with the nearby VP3300 device with the internal identifier equal to the provided UUID value.

Note that on iOS, the CoreBluetooth framework generated internal identifiers are not unique across time.

Sample data (Swift)

let uuid = "d1554880-56ac-11ed-9b6a-0242ac120002";

customUI.connect(withUUID: uuid);

Sample data (Objective C)

NSString* uuid = @"d1554880-56ac-11ed-9b6a-0242ac120002";

[customUI connectWithUUID:uuid];

DisconnectFromCurrentDevice

Attempts to break the connection between the application & the card reader.

If the card reader is not connected to the app, a card reader event similar to “disconnected already” is raised.

Otherwise, the SDK attempts to disconnect the card reader. If successful, the “disconnected” card reader event is raised.

Sample data (Swift)

customUI.disconnectFromCurrentDevice();

Sample data (Objective C)

[customUI disconnectFromCurrentDevice];

StartTransaction

Starts a transaction between an already connected application & the card reader.

Once the transaction starts, the card reader is ready to accept cards, either via swipe, tap or insert. This method can timeout. Default value is 10 seconds. Developers can override this value via the “parameters” object.

Sample data (Swift)

let prms : TransactionParameters = TransactionParameters.init()

prms.xAmount = 1.23;

prms.xInvoice = "1234";

prms.xCommand = "cc:sale";

prms.vp3300TransactionTimeout = 13;

customUI.startTransaction(withArgs: prms);

Sample data (Objective C)

TransactionParameters *prms = [[TransactionParameters alloc] init];

prms.xAmount = 1.23;

prms.xCommand = @"cc:sale";

prms.xInvoice = @"1235";

prms.xCustom01 = @"custom note";

prms.VP3300TransactionTimeout = 10;[customUI startTransactionWithArgs:prms];

CancelTransaction

Attempts to cancel an already started transaction between the application & the card reader.

If no transactions are started when this function is called, the function does not do anything.

Sample data (Swift)

customUI.cancelTransaction();

Sample data (Objective C)

[customUI cancelTransaction];

Available commands

Any of the following credit card commands are available for Custom UI:

cc:save
cc:credit
cc:authonly
cc:sale

Reference: Transaction API

Custom UI flow

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)

Function

Description

getVersion

Reads the SDK version

Returns a “cardknox sdk version” object

access to the Semantic Versioning “string” value
access to all individual parts: major, minor, patch, build

Sample data (Swift)

let ver = CardknoxSDK.getVersion() as! CardknoxSDKVersion

// Read the version in format "major.minor.patch.build"

let semanticVersion = ver.description();

// Access individual parts as well

let major : Int32 = ver.major;

let minor : Int32 = ver.minor;

let patch : Int32 = ver.patch;

let build : Int32 = ver.build;

Sample data (Objective C)

CardknoxSDKVersion *ver = [CardknoxSDK getVersion];

// Read the version in format "major.minor.patch.build"

NSString *semanticVersion = [ver description];

// Access individual parts as well

int major = [ver major];

int minor = [ver minor];

int patch = [ver patch];

int build = [ver build];

Logging

SDK verbose logging can be enabled or disabled with a function call:

Function

Description

EnableLogging

Accepts a boolean.

Enables or disabled the verbose logging.

Sample data (Swift)

CardknoxSDK.enableLogging(false);

Sample data (Objective C)

[CardknoxSDK enableLogging:true];

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

Last updated 9 months ago