Android SDK

Overview
Cardknox Android SDK is a mobile SDK targeted towards Android developers, allowing developers to process transactions with the Cardknox Transactions API.
Getting started
To start, download the SDK framework file:
​Android SDK download​
Integrate the SDK file into your Android Studio 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
Download our sample applications:
​Java sample app​
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
Sample data
setSoftwareConfigurations
Specifies the name of your software (xSoftwareName), version number of your software (xSoftwareVersion) and the gateway version (xVersion)
CardknoxSDK.setSoftwareConfigurations("Your app name", "0.0.1", "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.
CardknoxSDK.setPrincipalKey("ps_demo_cardknox");
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. The 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 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.
The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPoNum
The merchant’s purchase order number for the transaction.
123485
xDescription
This is a description
This is a description
xName
The cardholder’s name.
John Doe
xBillFirstName
The customer’s first name for their billing profile.
John
xBillLastName
The customer’s last/family name for their billing profile.
Doe
xBillCompany
The customer’s company name for their billing profile.
Acme
xBillStreet
The customer’s street address for their billing profile.
123 Any Street
xBillStreet2
The customer’s second street address for their billing profile.
123 Any Street
xBillCity
The customer’s city for their billing profile.
Anytown
xBillState
The customer’s state for their billing profile.
NY
xBillZip
The customer’s zip code for their billing profile.
12345
xBillCountry
The customer’s phone number for their billing profile.
USA
xBillPhone
The customer’s phone number for their billing profile.
8005551212
xShipFirstName
The customer’s last/family name for their shipping profile.
John
xShipLastName
The customer’s last/family name for their shipping profile.
Doe
xShipCompany
The customer’s company name for their shipping profile.
Acme
xShipStreet
The customer’s street address for their shipping profile.
123 Any Street
xShipStreet2
The customer’s second street address for their shipping profile.
123 Any Street
xShipCity
The customer’s city for their shipping profile.
Anytown
xShipState
The customer’s state for their shipping profile.
NY
xShipZip
The customer’s zip code for their shipping profile.
12345
xShipCountry
The customer’s country for their shipping profile.
USA
xShipPhone
The customer’s phone number for their shipping profile.
1113333444
xCustom01
Custom field 1. Use this for any additional data
​
xCustom02
Custom field 2. Use this for any additional data
​
xCustom03
Custom field 3. Use this for any additional data
​
xAuthCode
xAuthCode is a verification number provided by the issuing bank to be used with the cc:postauth command.
​
xAllowDuplicate
By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
False
xCustReceipt
True/False value indicating if the email address specified in xEmail should receive a receipt containing the transaction details.
False
xEmail
The customer’s email address.
[email protected]
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 registering BroadcastReceivers with IntentFilters, using a predefined value from the SDK for the “action” parameter.
The SDK uses the same “action” 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 register a BroadcastReceiver to receive appropriate information back from the SDK.
Transaction result callback subscription
This callback delivers a “transaction processed response” object to the subscriber.
Subscription can be made in the appropriate Fragment lifecycle method:
1
import android.content.BroadcastReceiver;
2
import android.content.Context;
3
import android.content.Intent;
4
import android.content.IntentFilter;
5
​
6
import androidx.annotation.NonNull;
7
import androidx.fragment.app.Fragment;
8
​
9
import cardknox.payments.sdk.CardknoxSDK;
10
import cardknox.payments.sdk.PaymentTransactionResponse;
11
​
12
public class TransactionResultExampleFragment extends Fragment {
13
​
14
    @Override
15
    public void onAttach(@NonNull Context context) {
16
        super.onAttach(context);
17
        RegisterIntentFilters();
18
    }
19
​
20
    @Override
21
    public void onDetach() {
22
        super.onDetach();
23
        UnregisterIntentFilters();
24
    }
25
​
26
    private void RegisterIntentFilters()
27
    {
28
        Context c = getContext();
29
​
30
        if(c != null)
31
        {
32
            c.registerReceiver(Receiver_TransactionProcessing, new IntentFilter(CardknoxSDK.TRANSACTION_CALLBACK_INTENTFILTER_ACTION()));
33
        }
34
    }
35
​
36
    private void UnregisterIntentFilters()
37
    {
38
        Context c = this.getContext();
39
​
40
        if(c != null)
41
        {
42
            c.unregisterReceiver(Receiver_TransactionProcessing);
43
        }
44
    }
45
​
46
    private final BroadcastReceiver Receiver_TransactionProcessing = new BroadcastReceiver() {
47
        @Override
48
        public void onReceive(Context context, Intent intent)
49
        {
50
            String action = intent.getAction();
51
​
52
            // Verify that the Cardknox SDK broadcasted the Intent
53
            if(action.equals(CardknoxSDK.TRANSACTION_CALLBACK_INTENTFILTER_ACTION()))
54
            {
55
                String extraKey = CardknoxSDK.TRANSACTION_CALLBACK_INTENTFILTER_EXTRA();
56
                java.lang.Object extra = intent.getParcelableExtra(extraKey);
57
​
58
                // Cast the 'extra' to the Cardknox SDK response type
59
                PaymentTransactionResponse response = (PaymentTransactionResponse)extra;
60
​
61
                if(response.GetIsSuccess())
62
                {
63
                    // Transaction successfully processed
64
                    String xRefNum = response.GetxRefNum();
65
                    // approved, declined, ...
66
                    String xStatus = response.GetxStatus();
67
                    String cvv = response.GetxCvvResult();
68
                    String avs = response.GetxAvsResult();
69
                    // ... other properties ...
70
​
71
                    Output("Transaction approved. Ref num: " + xRefNum);
72
                }
73
                else
74
                {
75
                    // Transaction processing resulted in an error; message can be extracted from this property:
76
                    String errorMessage = response.GetErrorMessage();
77
                    String errorCode = response.GetxErrorCode();
78
                    String error = response.GetxError();
79
​
80
                    Output("Transaction declined/errored. Ref num: " + response.GetxRefNum());
81
                }
82
            }
83
        }
84
    };
85
​
86
    private void Output(String text)
87
    {
88
        android.util.Log.d("ExampleTag", text);
89
    }
90
}
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 nearby 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 a bluetooth pairing is established, 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.
Subscription can be made in the appropriate Fragment lifecycle method:
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
​
import androidx.annotation.NonNull;
import androidx.fragment.app.Fragment;
​
import cardknox.payments.sdk.CardknoxCardReaderCallback;
import cardknox.payments.sdk.CardknoxCardReaderCallbackType;
import cardknox.payments.sdk.CardknoxSDK;
​
public class CardReaderEventsExampleFragment extends Fragment {
    @Override
    public void onAttach(@NonNull Context context) {
        super.onAttach(context);
        RegisterIntentFilters();
    }
​
    @Override
    public void onDetach() {
        super.onDetach();
        UnregisterIntentFilters();
    }
​
    private void RegisterIntentFilters()
    {
        Context c = getContext();
​
        if(c != null)
        {
            c.registerReceiver(Receiver_CardReaderEvents, new IntentFilter(CardknoxSDK.CARDREADER_CALLBACK_INTENTFILTER_ACTION()));
        }
    }
​
    private void UnregisterIntentFilters()
    {
        Context c = this.getContext();
​
        if(c != null)
        {
            c.unregisterReceiver(Receiver_CardReaderEvents);
        }
    }
​
    private final BroadcastReceiver Receiver_CardReaderEvents = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent)
        {
            String action = intent.getAction();
​
            // Verify that the Cardknox SDK broadcasted the Intent
            if(action.equals(CardknoxSDK.CARDREADER_CALLBACK_INTENTFILTER_ACTION()))
            {
                String extraKey = CardknoxSDK.CARDREADER_CALLBACK_INTENTFILTER_EXTRA();
                CardknoxCardReaderCallback callback = intent.getParcelableExtra(extraKey);
​
                // Read the event code
                int code = callback.GetCode();
​
                // Read the event name
                String name = callback.GetName();
​
                Output("Card reader event: " + name);
​
                // Match the non-error code; for example "connected"
                if(code == CardknoxCardReaderCallbackType.CONNECTED){
                    Output("Connected!");
                }
​
                // Extract the message when there's an error
                if(code == CardknoxCardReaderCallbackType.ERROR){
                    String message = callback.GetMessage();
                    Output("Card reader event: " + message);
                }
            }
        }
    };
​
    private void Output(String text)
    {
        android.util.Log.d("ExampleTag", text);
    }
}
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".
Developers 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.
disconnectedAlready
Applicable to the “custom ui” integration.
Raised when a “disconnect from current device” is called but there are no connected card readers to disconnect from.
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.
transactionStartErrorTimeout
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 20 seconds) and the transaction times out.
transactionStartDeviceDisconnected
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 could go wrong (list is not exhaustive) 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
A 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.
1
import android.content.BroadcastReceiver;
2
import android.content.Context;
3
import android.content.Intent;
4
import android.content.IntentFilter;
5
​
6
import androidx.annotation.NonNull;
7
import androidx.fragment.app.Fragment;
8
​
9
import cardknox.payments.sdk.CardknoxSDKCustomUI;
10
import cardknox.payments.sdk.CardknoxSDKCustomUIScannedDevice;
11
​
12
public class ScannedDeviceExampleFragment extends Fragment {
13
    @Override
14
    public void onAttach(@NonNull Context context) {
15
        super.onAttach(context);
16
        RegisterIntentFilters();
17
    }
18
​
19
    @Override
20
    public void onDetach() {
21
        super.onDetach();
22
        UnregisterIntentFilters();
23
    }
24
​
25
    private void RegisterIntentFilters()
26
    {
27
        Context c = getContext();
28
​
29
        if(c != null)
30
        {
31
            c.registerReceiver(Receiver_ScannedDevice, new IntentFilter(CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_ACTION()));
32
        }
33
    }
34
​
35
    private void UnregisterIntentFilters()
36
    {
37
        Context c = this.getContext();
38
​
39
        if(c != null)
40
        {
41
            c.unregisterReceiver(Receiver_ScannedDevice);
42
        }
43
    }
44
​
45
    private final BroadcastReceiver Receiver_ScannedDevice = new BroadcastReceiver() {
46
        @Override
47
        public void onReceive(Context context, Intent intent)
48
        {
49
            String action = intent.getAction();
50
​
51
            // Verify that the Cardknox SDK broadcasted the Intent
52
            if(action.equals(CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_ACTION()))
53
            {
54
                String extraKey = CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_EXTRA();
55
                java.lang.Object extra = intent.getParcelableExtra(extraKey);
56
​
57
                CardknoxSDKCustomUIScannedDevice device = (CardknoxSDKCustomUIScannedDevice) extra;
58
                // Can be used with a 'connect' method, like so:
59
                String address = device.GetAddress();
60
                CardknoxSDKCustomUI example = null;
61
                example.connectWithAddress(address);
62
                
63
                // Output various data about the device
64
                Output("Scanned device name: " + device.GetName());
65
                Output("Scanned device display name: " + device.GetDisplayName());
66
                Output("Scanned device address: " + device.GetAddress());
67
            }
68
        }
69
    };
70
​
71
    private void Output(String text)
72
    {
73
        android.util.Log.d("ExampleTag", text);
74
    }
75
}
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.
Subscription can be made in the appropriate Fragment lifecycle method:
1
import android.content.BroadcastReceiver;
2
import android.content.Context;
3
import android.content.Intent;
4
import android.content.IntentFilter;
5
​
6
import androidx.annotation.NonNull;
7
import androidx.fragment.app.Fragment;
8
​
9
import cardknox.payments.sdk.CardknoxSDKCustomUI;
10
import cardknox.payments.sdk.CardknoxSDKCustomUIScanCompleted;
11
import cardknox.payments.sdk.CardknoxSDKCustomUIScannedDevice;
12
​
13
public class ScanCompletedExampleFragment extends Fragment {
14
    @Override
15
    public void onAttach(@NonNull Context context) {
16
        super.onAttach(context);
17
        RegisterIntentFilters();
18
    }
19
​
20
    @Override
21
    public void onDetach() {
22
        super.onDetach();
23
        UnregisterIntentFilters();
24
    }
25
​
26
    private void RegisterIntentFilters()
27
    {
28
        Context c = getContext();
29
​
30
        if(c != null)
31
        {
32
            c.registerReceiver(Receiver_ScanCompleted, new IntentFilter(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION()));
33
        }
34
    }
35
​
36
    private void UnregisterIntentFilters()
37
    {
38
        Context c = this.getContext();
39
​
40
        if(c != null)
41
        {
42
            c.registerReceiver(Receiver_ScanCompleted, new IntentFilter(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION()));
43
        }
44
    }
45
​
46
    private final BroadcastReceiver Receiver_ScanCompleted = new BroadcastReceiver() {
47
        @Override
48
        public void onReceive(Context context, Intent intent)
49
        {
50
            String action = intent.getAction();
51
​
52
            // Verify that the Cardknox SDK broadcasted the Intent
53
            if(action.equals(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION()))
54
            {
55
                String extraKey = CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_EXTRA();
56
                java.lang.Object extra = intent.getParcelableExtra(extraKey);
57
                CardknoxSDKCustomUIScanCompleted scanCompleted = (CardknoxSDKCustomUIScanCompleted) extra;
58
​
59
                if(scanCompleted != null && scanCompleted.scannedDevices() != null &&
60
                        scanCompleted.scannedDevices().size() > 0)
61
                {
62
                    for (Object device : scanCompleted.scannedDevices()) {
63
                        CardknoxSDKCustomUIScannedDevice device = (CardknoxSDKCustomUIScannedDevice)d;
64
​
65
                        // Can be used with a 'connect' method, like so:
66
                        String address = device.GetAddress();
67
                        CardknoxSDKCustomUI example = null;
68
                        example.connectWithAddress(address);
69
​
70
                        // Output various data about the device
71
                        Output("Scanned device name: " + device.GetName());
72
                        Output("Scanned device display name: " + device.GetDisplayName());
73
                        Output("Scanned device address: " + device.GetAddress());
74
                    }
75
                }
76
            }
77
        }
78
    };
79
​
80
    private void Output(String text)
81
    {
82
        android.util.Log.d("ExampleTag", text);
83
    }
84
}
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:
CardknoxSDKUI cardknoxSDKUI = 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 androidx.fragment.app.Fragment;
​
import cardknox.payments.sdk.CardknoxSDKUI;
​
public class OutOfScopeExampleFragment extends Fragment {
​
    private CardknoxSDKUI cardknoxSDKUI;
​
    @Override
    public void onResume() {
        super.onResume();
        cardknoxSDKUI = CardknoxSDKUI.create();
    }
​
     @Override
    public void onDetach() {
        super.onDetach();
        
        // This might not be the best place where to destroy the 'cardknox sdk ui' object.
        //
        // Why:
        // The Cardknox SDK starts a new Activity to show its' UI; effectively
        // pausing all other components. 
        // It relies on the 'cardknox sdk ui' reference not being destroyed.
        destroyCardknoxSDKUI();
    }
​
    /**
     * Destroy the 'cardknox sdk ui' manager object when it's no longer needed.
     * 
     * Call this when:
     * 1. your UI component (Activity, Fragment, etc.) needs to close itself.
     * 
     * Do not call this when:
     * 1. the Cardknox SDK needs to show its' UI as it relies on the 'cardknox sdk ui' reference not being destroyed
     * */
    private void destroyCardknoxSDKUI(){
        if (cardknoxSDKUI != null) {
            cardknoxSDKUI.destroy();
        }
        cardknoxSDKUI = null;
    }
}
To show the user interface, create a request object that is capable of showing a user interface:
// Create the parameters object
TransactionParameters parameters = new TransactionParameters()
{
    {
        // Required parameters
        // 1. command to use. One of the Cardknox Transaction API commands
        SetxCommand("cc:sale");
        // 2. amount
        SetxAmount(1.23);
​
        // Supplementary parameters
        // 1. card number - will be prefilled on the keyed form
        SetxCardNum("4444333322221111");
​
        // 2. expiration date - will be prefilled on the keyed form
        // Format "MMYY"
        // For example: December 2024
        SetxExp("1224");
​
        // Optional parameters to supplement the transaction
        // All of the available parameters will be sent to the gateway
        SetxInvoice("1234");
        SetxBillCity("New York");
        // ... other optional parameters.
    }
};
​
PaymentTransactionRequestUI request = cardknoxSDKUI.createRequestWithParameters(parameters);
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:
PaymentTransactionRequestUI request = cardknoxSDKUI.createRequestWithParameters(parameters);
​
if(request.GetIsValid()){
    // Supply the Activity reference here.
    // In fragments, that might be a 'getActivity()' call.
    android.app.Activity activity = null;
    
    // Show Cardknox SDK UI
    request.process(activity);
} else {
    // Extract all validation errors that block
    // the request object from showing the SDK UI
    String[] validationErrors = request.GetValidationErrors();
}
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
Sample data
EnableDeviceInsertSwipeTap
Globally configures the SDK to show the keyed screen that allows manual input interaction.
CardknoxSDKUI.SetEnableDeviceInsertSwipeTap(true);
EnableKeyedEntry
Globally configures the SDK to show the swipe screen that allows card reader interaction.
CardknoxSDKUI.SetEnableKeyedEntry(true);
The following mapping represents which screens will be available when the SDK shows its user interface:
EnableDeviceInsertSwipeTap
EnableKeyedEntry
Keyed screen available
Swipe screen available
false
false

Function	Description	Sample data
setSoftwareConfigurations	Specifies the name of your software (xSoftwareName), version number of your software (xSoftwareVersion) and the gateway version (xVersion)	`CardknoxSDK.setSoftwareConfigurations("Your app name", "0.0.1", "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.	`CardknoxSDK.setPrincipalKey("ps_demo_cardknox");`

Function	Description	Sample data
EnableDeviceInsertSwipeTap	Globally configures the SDK to show the keyed screen that allows manual input interaction.	`CardknoxSDKUI.SetEnableDeviceInsertSwipeTap(true);`
EnableKeyedEntry	Globally configures the SDK to show the swipe screen that allows card reader interaction.	`CardknoxSDKUI.SetEnableKeyedEntry(true);`

EnableDeviceInsertSwipeTap	EnableKeyedEntry	Keyed screen available	Swipe screen available
false	false

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

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

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.
disconnectedAlready	Applicable to the “custom ui” integration. Raised when a “disconnect from current device” is called but there are no connected card readers to disconnect from.
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.
transactionStartErrorTimeout	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 20 seconds) and the transaction times out.
transactionStartDeviceDisconnected	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 could go wrong (list is not exhaustive) 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 A descriptive error message is always accompanying this event.