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 | | Device status |The SDK is sending information to subscribers about the device initialization process and the actions that the device expects from the user of the card scanner.
For example, waiting for the insert or swipe of a credit card.
The Sola 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 Sola SDK with a “connecting” event.
The Sola SDK raises a “connecting” callback which notifies the app.
| | waitingForDeviceResponse |This event is raised whenever the Sola 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. Sola 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 Sola SDK presents its user interface; automatically starting a bluetooth scan for a nearby card reader, expecting a response back
Raised when the app & the card reader establish a bluetooth connection.
Bluetooth connection is established when the Sola SDK scans for card readers, and card readers respond back with some bluetooth payload.
| | disconnected |Card reader SDK sends this event to the Sola SDK whenever a bluetooth card reader goes to sleep.
This event is never raised explicitly by the Sola SDK.
| | transactionStarting |Informational event.
Sola 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 |Sola SDK attempts a “start transaction” call with the card reader SDK.
Card reader SDK successfully starts the transaction and notifies the Sola SDK with this event.
Sola SDK calls back with this event to the app.
| | transaction start error timeout |Sola 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 | Sola 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 Sola 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 Sola 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
Indicates that the Sola 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
Indicates that the Sola 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
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: {% code lineNumbers="true" %} ```swift 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(); } } ``` {% endcode %} #### Scan completed callback subscription One of the Custom UI integration functions is a “start scanning” function. The function keeps scanning for nearby bluetooth devices until it is manually stopped with the “stop scanning” function or if it times out. Once the scanning process ends, the SDK sends a list of scanned device objects to all subscribers. Any object in the retrieved list can be used as an argument to the “connect to device” method. For Swift applications using Swift UI, subscription can be made in a View as follows: {% code lineNumbers="true" %} ```swift 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 : ArrayExample of a keyed user interface. Keyed screen has a top right corner icon to navigate to the swipe screen.
Example of a swipe user interface. The swipe screen contains a button on the bottom that navigates the user to the keyed user interface.
Any of the following credit card commands:
- cc:save
- cc:credit
- cc:authonly
- cc:sale
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();
| #### 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** | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | CloseSDKOnUIProcessedTransaction |Globally configures the SDK to auto close the user interface after processing a transaction.
Default value is false.
| | | **Sample data (Swift)** | | | CardknoxSDKUI.setCloseOnProcessedTransaction(true); |   ### In scope integration In scope processing feature allows the developer to quickly process a payment and retrieve the response object. To process directly, create a request object: {% tabs %} {% tab title="Swift" %} {% code lineNumbers="true" %} ```swift // 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; ``` {% endcode %} {% endtab %} {% endtabs %} ```swift // 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]; ``` 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: {% tabs %} {% tab title="Swift" %} ```swift 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; } ``` {% endtab %} {% endtabs %} ```swift 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)](https://docs.solapayments.com/api/transaction/check-ach) * Credit Card commands * Reference: [Credit Card](https://docs.solapayments.com/api/transaction/credit-card) * EBT Food Stamp commands * Reference: [EBT Food Stamp](https://docs.solapayments.com/api/transaction/ebt#ebt-food-stamp) * EBT Cash Benefits * Reference: [EBT Cash Benefits](https://docs.solapayments.com/api/transaction/ebt#ebt-cash-benefits) * EBT Wic * Reference: [EBT Wic](https://docs.solapayments.com/api/transaction/ebt#ebt-wic-ewic) * Gift Card commands * Reference: [Gift Card](https://docs.solapayments.com/api/transaction/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** | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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.
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** | | | 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
let scannedDevice : String = nil;
customUI.connect(toDevice: scannedDevice);
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** | | |let uuid = "d1554880-56ac-11ed-9b6a-0242ac120002";
customUI.connect(withUUID: uuid);
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** | | | 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.
let prms : TransactionParameters = TransactionParameters.init()
prms.xAmount = 1.23;
prms.xInvoice = "1234";
prms.xCommand = "cc:sale";
prms.vp3300TransactionTimeout = 13;
customUI.startTransaction(withArgs: 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** | | | 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](https://docs.solapayments.com/api/transaction/credit-card) #### 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. ### Payment engine integration The Payment Engine won't show any UI. The developer provides the user interface and uses three payment engine functions to create transactions with a card reader over IP. Data that is required to create a transaction is passed by developers as parameters to those SDK functions. The messages and results of creating a transaction with the Payments engine are obtained by the developer from transaction result callback, device status callback, and transaction status. | Device\_Initialize |This function makes sure that the mobile device can communicate with the card reader and saves data that is needed for connecting to the card reader.
The initialization process can take about 2 minutes. But it is sufficient to execute it once per card reader and IP address.
| | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Sample data** | | |let settings : CardknoxPaymentEngineSDKSettings
CardknoxPaymentEngineSDKSettings.init();
settings.device\_Name = "Verifone\_P400.4";
settings.device\_IP\_Address = “127.21.2.7”;
settings.device\_IP\_Port = “9006”;
settings. device\_Timeout = 120 \* 1000; // seconds
CardknoxSDK.create().getPaymentEngine().device\_Initialize(withSettings: settings)
| | ProcessOutOfScopeWithSettings |Attempts to create a transaction with a card reader over IP.
This function will perform the initialization process if initialization has not been performed for the specific card reader.
| | | **Sample data** | | |let settings : CardknoxPaymentEngineSDKSettings
CardknoxPaymentEngineSDKSettings.init();
settings.device\_Name = "Verifone\_P400.4";
settings.device\_IP\_Address = “127.21.2.7”;
settings.device\_IP\_Port = “9006”;
settings. device\_Timeout = 120 \* 1000; // seconds
let request : CardknoxPaymentEngineSDKRequest = CardknoxPaymentEngineSDKRequest.init();
request.xAmount = 1.23
request.xCommand = "cc:sale";
CardknoxSDK.create().getPaymentEngine().processOutOfScope(withSettings: settings, request: request)
| | Device\_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** | | | CardknoxSDK.create().getPaymentEngine().device\_CancelTransaction(); | ### Versioning Developers can call the “get version” API to obtain the SDK Semantic Versioning ([SemVer source](https://semver.org/)) | **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
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 1. As a Sola 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 2. As a Sola 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 Sola 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.solapayments.com/sdk/ios-sdk.md?ask=