iOS SDK

Overview

CardknoxPaymentsSDK is a mobile SDK targeted towards Objective C / Swift mobile application developers; it allows developers to process transactions with the Cardknox Transactions API.

Features

The SDK provides 2 main features:

  1. To process a transaction with the Cardknox user interface. This mode is also called “out of scope.” User is able to process a transaction either through a manual form or through a physical card reader device. The request type, provided by the SDK, contains multiple constructors for “out of scope“ processing for both the manual form, either with a reference number of card number processing, and the card reading user interface. Currently supported card reader is the IDTech VP3300, in Bluetooth mode. The SDK will deliver the transaction processing results to the native application through the NSNotificationCenter.

  2. To process a transaction without the Cardknox user interface. This mode is also called “in scope.” This mode should be used to quickly process a transaction using the Cardknox SDK. Results are given back as a function return value.

Technical Overview

  • The SDK is distributed as a .framework

  • .framework contains the CardknoxPaymentsSDK binary and ObjectiveC .h headers describing the SDK API

  • the CardknoxPaymentsSDK does not contain bitcode and cannot be integrated with applications that require bitcode

  • .framework only supports arm64 64-bit architecture for device builds - simulator targets are not supported

  • SDK minimum deployment target is 9.3

Getting started

To start:

  1. Download the .framework.

  2. Add it to your XCode project to the application Target:

CardknoxPaymentsSDK.framework added to a sample app Target

SDK API Overview

The CardknoxPaymentsSDK provides the following objects:

  • CardknoxSDK - Used to initialize the CardknoxPaymentsSDK with client metadata, such as client’s software name and software version, as well as with the Cardknox API key to associate processed transactions with. Additionally, the type exposes a handful of lifecycle methods, which are named appropriately with their counterpart in the respective client’s class where they are meant to be called in. It is important for the CardknoxPaymentsSDK lifecycle methods to be in sync with their client’s app lifecycle in order to initialize and dispose of the internal data structures.

  • PaymentTransactionRequest - A request type. Type’s constructor arguments represents the bare minimum of required parameters to make a transaction request against the Cardknox API. Developers can call in scope and out of scope functions on an instance of this type to process a transaction.

  • PaymentTransactionResponse - A response type that is the result of both the in scope and out of scope functions. This object is returned by the in scope function or delivered via the NSNotificationCenter for the out of scope function. For out of scope function, this type offers a utility conversion static method to convert the NSNotification object into an instance of this type.

  • CardknoxCardReaderCallback - A type representing a callback when the SDK is being used to process ‘out of scope’ transactions using a physical card reader device. To receive callbacks back from the SDK, the user needs to subscribe with the NSNotificationCenter by using a tag value on the PaymentTransactionRequest type.

  • CardknoxCallbackCardReaderType - a type containing an enumeration of all possible callback types. Each CardknoxCardReaderCallback object received through the NSNotificationCenter contains one enumeration value.

Object definitions can be found in the framework’s subfolder Headers in any of the registrar- prefixed files such as registrar-arm64or registrar-x86_64. Registrar files can differ in content, but all of them provide identical definitions for CardknoxPaymentsSDK defined objects.

CardknoxSDK Type

Cardknox SDK object definition
Cardknox SDK Object Definition
Cardknox SDK Object Definition

Function

Description

initWithxSoftwareName:(NSString *)p0 xSoftwareVersion:(NSString *)p1

xVersion:(NSString *)p2

Configures the SDK with xSoftwareName, xSoftwareVersion and xVersion parameters. These parameters are metadata that describe the client’s application. These parameters will be sent to the Cardknox Gateway at the time of transaction processing.

As per the Cardknox Transaction API documentation:

  • xSoftwareName - Name of your software.

  • xSoftwareVersion - Version of your software.

  • xVersion - Cardknox API version. The current version is 4.5.9.

For an ObjectiveC application, call spot is:

application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

Note that this method should be the first method to be called from the CardknoxPaymentsSDK.

Sample Data

Function

Description

dealloc

Deallocates/disposes of all CardknoxPaymentsSDK internal data structures.

This method should be called when the CardknoxPaymentsSDK is no longer used; for example when the mobile application is about to terminate.

To use the CardknoxPaymentsSDK again after a call to this method, call the init function on the SDK.

Sample Data

Function

Description

applicationDidFinishLaunching

Attaches the CardknoxPaymentsSDK to the AppDelegate’s lifecycle method.

This method should be called after initWithxSoftwareName method.

Sample Data

Function

Description

applicationWillEnterForeground

Attaches the CardknoxPaymentsSDK to the AppDelegate’s lifecycle method.

Function

Description

applicationDidEnterBackground

Attaches the CardknoxPaymentsSDK to the AppDelegate’s lifecycle method.

Sample Data

Function

Description

applicationDidEnterBackground

Attaches the CardknoxPaymentsSDK to the AppDelegate’s lifecycle method.

Sample Data

Function

Description

setPrincipalKey:(NSString *)p0

From the Cardknox Transaction API documentation:

Calling this method configures the CardknoxPaymentsSDK to use the specific Cardknox API key for every subsequent transaction processed with the CardknoxPaymentsSDK. If the user wishes to process more transactions with a different Cardknox API, then this is the method that needs to be called.

Sample Data

CardknoxSDK functions

PaymentTransactionRequest Type

PaymentTransactionRequest object definition
First Tab
Second Tab
First Tab

Function

Description

processOutOfScope_NotificationTag

Read-only NSString property.

Developers need to use this tag when adding an observer to the NSNotificationCenter in order to receive a PaymentTransactionResponse object prior to invoking the processOutOfScope function.

Sample Data

Function

Description

processOutOfScope_CardReaderCallbackNotificationTag

Read-only NSString property.

Developers need to use this tag when when adding an observer to the NSNotificationCenter in order to receive a CardknoxCardReaderCallback object value from the SDK into the mobile application about the card reader status.

See the CardknoxCardReaderCallbackType type for a list of all possible callbacks.

Sample Data

Function

Description

isValid

Read-only BOOL property.

Represents the validity of the PaymentTransactionRequest object instance.

Value is computed through PaymentTransactionRequest constructor functions.

Sample Data

True/False

Function

Description

ValidationErrors

Read-only NSArray property.

Value is a nil NSArray when the isValid value is TRUE.

Value is an non-empty NSArray when the isValid value is FALSE. It contains a user-friendly validation error message for each invalid property on the PaymentTransactionRequest object instance.

Sample Data

  1. xExp provided value is ““, error is “xExp field is invalid (null, empty or pure whitespace)”

  2. xExp provided value is “021”, error is: xExp parameter should be 4 characters long. Expecting 4 digit characters where first 2 digits are months, and second 2 digits year (2/2020 should be passed in as 0220)

  3. xExp provided value contains a non-digit or a non-integer value is passed in. For example, if the value is “a03”, the error is: Unable to parse an integer number out of xExp value. Expecting a string with 4 digit characters.

Second Tab

PaymentTransactionRequest properties

First Tab
Second Tab
First Tab

Function

Description

(id) createOutOfScopeRequestWithxRefNum:(NSString *)p0 xCommand:(NSString *)p1

Constructor function.

Calling processOutOfScope function on an instance of this object will show the UI manual entry form to process using the reference number value.

Calling processInScope is a no-op.

Object state validity can be read by invoking the (BOOL) isValid function on the same object instance.

In case the object is not valid (i.e., the (BOOL) isValid) function returns NO), the (NSArray *) ValidationErrors property returns an array of validation errors for each invalid parameter.

Parameter definitions:

Sample Data

Function

Description

(id) createOutOfScopeRequestWithxAmount:(double)p0 xExp:(NSString *)p1 xCardNum:(NSString *)p2 xCommand:(NSString *)p3

Constructor function.

Calling processOutOfScope function on an instance of this object will show the UI manual entry form to process using the card number, expiration date and amount values.

Calling processInScope is a no-op.

Object state validity can be read by invoking the (BOOL) isValid function on the same object instance.

In case the object is not valid (i.e., the (BOOL) isValid) function returns NO), the (NSArray *) ValidationErrors property returns an array of validation errors for each invalid parameter.

Parameter definitions:

  • xAmount

    • a positive double number

  • xExp

    • expiration date, in format YYMM

  • xCardNum

    • a non empty string of characters. The SDK does not perform validation about the card type nor about the correct card number format

  • xCommand

    • supported values: cc:sale, cc:credit, cc:authonly

Sample Data

Function

Description

(id) createOutOfScopeCardReaderRequestWithxAmount:(double)p0 xCommand:(NSString *)p1

Constructor function.

Calling processOutOfScope function on an instance of this object will show the card reader UI form to process using a physical card reader device.

Calling processInScope is a no-op.

Object state validity can be read by invoking the (BOOL) isValid function on the same object instance.

In case the object is not valid (i.e., the (BOOL) isValid) function returns NO), the (NSArray *) ValidationErrors property returns an array of validation errors for each invalid parameter.

Parameter definitions:

  • xAmount

    • a positive double number

  • xCommand

    • supported values: cc:sale, cc:credit, cc:authonly

Sample Data

Fucntion

Description

(id) createInScopeRequestWithxAmount:(double)p0 xExp:(NSString *)p1 xCardNum:(NSString *)p2 xCommand:(NSString *)p3

Constructor function.

Calling processOutOfScope function is a no-op.

Calling processInScope function will process the transaction with the Cardknox Transactions API and return the response object as a function return value.

Parameter definitions:

xAmount

a positive double number

xExp

expiration date, in format YYMM

xCardNum

a non empty string of characters. The SDK does not perform validation about the card type nor about the correct card number format

xCommand

supported values: cc:sale, cc:credit, cc:authonly

Sample Data

Function

Description

(id) processInScope

Non-static function.

Processes the transaction ‘without user interface.’

The result is a non-nil PaymentTransactionResponse object.

Transaction processing outcome can be determined by reading from the isSuccess property on the response object. In case the object is not in a success state, errorMessage property can be read for more information.

Additionally, developers can read from (BOOL) isValid and (NSArray *) ValidationErrors properties on the PaymentTransactionRequest instance to further determine the case of a response object being in error state.

Sample Data

Function

Description

(id) processOutOfScope

Non-static function.

Shows the CardknoxPaymentsSDK user interface for transaction processing.

Prior to calling this function, in order to receive transaction processing results, developers need to opt-in for results received through the NSNotificationCenter addObserver method by using the CardknoxPaymentsSDK provided NSString tag called processOutOfScope_NotificationTag, available on the PaymentTransactionRequest type.

Sample Data

Second Tab

PaymentTransactionRequest functions

PaymentTransactionResponse Type

PaymentTransactionResponse object definition

Property

Description

Sample data

isSuccess

Read-only BOOL property.

TRUE is the PaymentTransactionResponse object whose instance represents a successfully processed transaction; FALSE otherwise.

TRUE / FALSE

errorMessage

Read-only NSString property.

A nil NSString if the isSuccess property is TRUE; otherwise contains a non-nil NSString value with an error message.

Calling the processInScope function on a PaymentTransactionRequest object, which as created with an unsupported xCommand would return a PaymentTransactionResponse object with errorMessage similar to:

Unable to execute method. Object state is invalid. Errors: xCommand provided value is not supported by the SDK. Supported commands are: cc:sale, cc:credit.

xResult

Transaction status

Cardknox API reference

A

E

D

xStatus

Result verbiage

Cardknox API reference

Approved

Error

Declined

xError

Error message, if applicable

See xErrorCode

xErrorCode

Error code

Cardknox API error codes list

Most common error codes: 00000 = Approved 01332 = Duplicate Transaction 1334 = Declined Transaction 01479 = Invalid Card

xRefNum

Cardknox transaction Reference Number. Note: xRefnum is always returned regardless of the outcome of the transaction.

Cardknox API reference

xDate

Time when the transaction was processed.

Value is URL encoded.

Value is localized to the Eastern Time (Abbr. ET) time zone.

Daylight savings are applied.

ET during winter is abbreviated as EST (Eastern Standard Time).

ET during summer is abbreviated as EDT (Eastern Daylight Time).

xDate=4%2f16%2f2021+10%3a14%3a44+AM

xAuthCode

Authorization code, approved transactions only.

Cardknox API reference

xBatch

Batch into which transaction will settle.

Cardknox API reference

xAvsResultCode

The Address Verification Service (AVS) response code.

Cardknox API reference

<code> = <verbiage>

YYY = Address: Match & 5 Digit Zip: Match NYZ = Address: No Match & 5 Digit Zip: Match YNA = Address: Match & 5 Digit Zip: No Match NNN = Address: No Match & 5 Digit Zip: No Match XXU = Address Information not verified for domestic transaction YYX = Address: Match & 9 Digit Zip: Match NYW = Address: No Match & 9 Digit Zip: Match XXR = Retry / System Unavailable XXS = Service Not Supported XXW = Card Number Not On File XXE = Address Verification Not Allowed For Card Type XXG = Global Non-AVS participant YYG = International Address: Match & Zip: Not Compatible GGG = International Address: Match & Zip: Match YGG = International Address: Not Compatible & Zip: Match

xAvsResult

AVS verbiage.

Cardknox API reference

See xAvsResultCode sample data.

xCvvResultCode

Card Code Verification (CCV) response code.

Cardknox API reference

<code> = <verbiage>

M = Match N = No Match P = Not Processed S = Should be on card, but not so indicated U = Issuer Not Certified X = No Response from Association

xCvvResult

CVV verbiage.

Cardknox API reference

See xAvsResult sample data.

xAuthAmount

The total amount authorized, inclusive of tax and tip (if applicable).

Cardknox API reference

xToken

Token returned for use with future transaction.

Cardknox API reference

xMaskedCardNumber

A masked version of the credit card used for the transaction.

Cardknox API reference

xCardType

Type of credit card used for the transaction.

Cardknox API reference

Unknown EBT GiftCard Amex Visa MasterCard Discover Diners JCB

PaymentTransactionResponse properties

PaymentTransactionResponse
PaymentTransactionResponse

Function

Description

(id) unwrap:(NSNotification *)p0

Static function.

Utility method to extract the PaymentTransactionResponse object from a NSNotification object when processing transactions with PaymentTransactionRequest processOutOfScope function.

Sample Data

PaymentTransactionResponse functions

CardknoxCardReaderCallback type

CardknoxCardReaderCallback type definition

Property

Description & sample data

(int) code

One of the property values on the CardknoxCardReaderCallbackType type.

CardknoxCardReaderCallback properties

Function

Description

+(id) unwrap:(NSNotification *)p0;

A utility method to convert an NSNotification object into a CardknoxCardReaderCallback object.

CardknoxCardReaderCallback functions

CardknoxCardReaderCallbackType type

CardknoxCardReaderCallbackType object definition

CardknoxCardReaderCallbackType object definition

Property

Description

connected

Raised when the CardknoxPaymentsSDK successfully discovers and connects to the physical card reader device.

connecting

Raised when the CardknoxPaymentsSDK initiates a discovery process, such as a bluetooth scan, in order to find and connect to the physical card reader device.

The discovery process lasts for 15 seconds.

connectingTimeout

Raised when the CardknoxPaymentsSDK initiates a discovery process, such as a bluetooth scan, in order to find a physical card reader device to connect to - but the discovery process times out.

disconnected

Raised when the physical card reader device raises a disconnected event.

transactionStarted

Raised when the transaction with the physical card reader is started and the card reader is ready to accept a card to read from.

transactionCancelled

Raised when the already started transaction with the physical card reader is cancelled.

For example, this callback is raised if there is an already started transaction and the CardknoxPaymentsSDK UI is closed.

errorCardReadTimeout

Raised when the card reader timed out when a physical card was either inserted into (EMV contact), tapped onto (EMV contactless) or swiped through (MSR) the physical card reader device.

A transaction with a card reader has to be established prior to this event potentially happening.

errorEMVCardDeclined

Raised when the physical card reader device declined an EMV card, for various reasons, during the card reading process.

Most often, a new transaction with the card reader will have to be established to read the card again.

errorEMVGenericError

A generic callback for EMV card reading errors.

errorMSRGenericError

A generic callback for MSR card reading errors.

Sample code for subscribing to the callbacks.

For example, this can be called from the viewDidLoad controller method on iOS

Sample code for handling various card reading callbacks: