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. 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. 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. 1.
    Download the .framework.
  2. 3.
    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
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.
  • 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
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
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. 1.
    xExp provided value is ““, error is “xExp field is invalid (null, empty or pure whitespace)”
  2. 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. 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.
PaymentTransactionRequest properties
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
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
A
E
D
xStatus
Result verbiage
Approved
Error
Declined
xError
Error message, if applicable
See xErrorCode
xErrorCode
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.
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.
xBatch
Batch into which transaction will settle.
xAvsResultCode
The Address Verification Service (AVS) response code.
<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.
See xAvsResultCode sample data.
xCvvResultCode
Card Code Verification (CCV) response code.
<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.
See xAvsResult sample data.
xAuthAmount
The total amount authorized, inclusive of tax and tip (if applicable).
xToken
Token returned for use with future transaction.
xMaskedCardNumber
A masked version of the credit card used for the transaction.
xCardType
Type of credit card used for the transaction.
Unknown EBT GiftCard Amex Visa MasterCard Discover Diners JCB
PaymentTransactionResponse properties
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:
Last modified 5d ago