Verifone\_P400.4
(The 4. column in Payment engine support device table)
| | Device\_IP\_Address | IP address of PE device | 172.21.2.7 | | Device\_Port | Port of PE device | 9006 | | Device\_Timeout | Timeout for PE device connecting | 120 | | VP3300StartTransactionMethod |The card reader can scan a card in a few different ways: swipe, tap, or insert a card. This property defines how the card reader expects the card to be scanned.
See SetVP3300StartTransactionMethod in Custom UI with USB section.
|Possible values:
- CTLS - tap a card (NFC)
- EMV - insert card
- MSR - swipe card
- DEVICE - swipe, insert and tap a card
Out of scope
Custom UI
Payment Engine
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.
| Payment Engine | | Transaction status | The transaction status sends information about the card scanning process. | Payment Engine | | Result as JSON | The result of created transaction return in JSON format. | Payment Engine | | Payment engine LogCat logging | The payment engine supports two types of event logging. One prints logs directly to the LogCat console, while the other delivers logs via callbacks, allowing the app to handle them programmatically. | Payment Engine | ### 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: {% code lineNumbers="true" %} ```javascript 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.CardknoxSDK; import cardknox.payments.sdk.PaymentTransactionResponse; public class TransactionResultExampleFragment 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_TransactionProcessing, new IntentFilter(CardknoxSDK.TRANSACTION_CALLBACK_INTENTFILTER_ACTION())); } } private void UnregisterIntentFilters() { Context c = this.getContext(); if(c != null) { c.unregisterReceiver(Receiver_TransactionProcessing); } } private final BroadcastReceiver Receiver_TransactionProcessing = 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.TRANSACTION_CALLBACK_INTENTFILTER_ACTION())) { String extraKey = CardknoxSDK.TRANSACTION_CALLBACK_INTENTFILTER_EXTRA(); java.lang.Object extra = intent.getParcelableExtra(extraKey); // Cast the 'extra' to the Cardknox SDK response type PaymentTransactionResponse response = (PaymentTransactionResponse)extra; if(response.GetIsSuccess()) { // Transaction successfully processed String xRefNum = response.GetxRefNum(); // approved, declined, ... String xStatus = response.GetxStatus(); String cvv = response.GetxCvvResult(); String avs = response.GetxAvsResult(); // ... other properties ... Output("Transaction approved. Ref num: " + xRefNum); } else { // Transaction processing resulted in an error; message can be extracted from this property: String errorMessage = response.GetErrorMessage(); String errorCode = response.GetxErrorCode(); String error = response.GetxError(); Output("Transaction declined/errored. Ref num: " + response.GetxRefNum()); } } } }; private void Output(String text) { android.util.Log.d("ExampleTag", text); } } ``` {% endcode %} #### 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: {% code lineNumbers="true" %} ```javascript 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); } } ``` {% endcode %} #### 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. 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 Cardknox 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 Cardknox SDK scans for card readers, and card readers respond back with some bluetooth payload.
| | disconnected |Card reader SDK sends this event to the Cardknox SDK whenever a bluetooth card reader goes to sleep.
This event is never raised explicitly by the Cardknox SDK.
| | transactionStarting |Informational event.
Cardknox SDK raises this event before it places a call to the underlying card reader SDK in order to start a transaction with the card reader.
| | transactionStarted |Cardknox SDK attempts a “start transaction” call with the card reader SDK.
Card reader SDK successfully starts the transaction and notifies the Cardknox SDK with this event.
Cardknox SDK calls back with this event to the app.
| | 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.
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
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
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
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.
| | swipe says use chip reader | This card reader event is raised when the card with a chip is swiped, to indicate that a “fallback Swipe” was blocked. Reach out to Sola support to consult about “fallback Swipe”. | | card inserted when ctls swipe requested | in some scenarios, the VP3300 will expect a Swipe, but will receive a card Insert. In such cases this event is raised. | | contactless in msr card read event | this event is raised when a Contactless MSD transaction is performed on a VP3300 device. | | USB detached |This event occurs when the USB cable is unplugged, causing the connection between the mobile device and the card reader to be interrupted. As a result, any ongoing communication or data transfer between the two devices is immediately stopped.
Note: Only available for Custom UI with USB integration.
| | USB device not found |This is raised when you try to connect to the card reader that's not plugged in with a USB cable.
Note: Only available for Custom UI with USB integration.
| | USB unsupported product |This means that the connected USB device is not supported by the system or the driver.
Note: Only available for Custom UI with USB integration.
| | USB permission not granted |This error occurs when the application does not have the necessary permission to access the connected USB device. The user must explicitly grant permission for the device to be recognized and used.
Note: Only available for Custom UI with USB integration.
| #### 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. Subscription can be made in the appropriate Fragment lifecycle method: {% code lineNumbers="true" %} ```javascript 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.CardknoxSDKCustomUI; import cardknox.payments.sdk.CardknoxSDKCustomUIScannedDevice; public class ScannedDeviceExampleFragment 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_ScannedDevice, new IntentFilter(CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_ACTION())); } } private void UnregisterIntentFilters() { Context c = this.getContext(); if(c != null) { c.unregisterReceiver(Receiver_ScannedDevice); } } private final BroadcastReceiver Receiver_ScannedDevice = 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(CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_ACTION())) { String extraKey = CardknoxSDKCustomUI.SCANNED_DEVICE_INTENTFILTER_EXTRA(); java.lang.Object extra = intent.getParcelableExtra(extraKey); CardknoxSDKCustomUIScannedDevice device = (CardknoxSDKCustomUIScannedDevice) extra; // Can be used with a 'connect' method, like so: String address = device.GetAddress(); CardknoxSDKCustomUI example = null; example.connectWithAddress(address); // Output various data about the device Output("Scanned device name: " + device.GetName()); Output("Scanned device display name: " + device.GetDisplayName()); Output("Scanned device address: " + device.GetAddress()); } } }; private void Output(String text) { android.util.Log.d("ExampleTag", text); } } ``` {% 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. Subscription can be made in the appropriate Fragment lifecycle method: {% code lineNumbers="true" %} ```javascript 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.CardknoxSDKCustomUI; import cardknox.payments.sdk.CardknoxSDKCustomUIScanCompleted; import cardknox.payments.sdk.CardknoxSDKCustomUIScannedDevice; public class ScanCompletedExampleFragment 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_ScanCompleted, new IntentFilter(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION())); } } private void UnregisterIntentFilters() { Context c = this.getContext(); if(c != null) { c.registerReceiver(Receiver_ScanCompleted, new IntentFilter(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION())); } } private final BroadcastReceiver Receiver_ScanCompleted = 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(CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_ACTION())) { String extraKey = CardknoxSDKCustomUI.SCAN_COMPLETED_INTENTFILTER_EXTRA(); java.lang.Object extra = intent.getParcelableExtra(extraKey); CardknoxSDKCustomUIScanCompleted scanCompleted = (CardknoxSDKCustomUIScanCompleted) extra; if(scanCompleted != null && scanCompleted.scannedDevices() != null && scanCompleted.scannedDevices().size() > 0) { for (Object device : scanCompleted.scannedDevices()) { CardknoxSDKCustomUIScannedDevice device = (CardknoxSDKCustomUIScannedDevice)d; // Can be used with a 'connect' method, like so: String address = device.GetAddress(); CardknoxSDKCustomUI example = null; example.connectWithAddress(address); // Output various data about the device Output("Scanned device name: " + device.GetName()); Output("Scanned device display name: " + device.GetDisplayName()); Output("Scanned device address: " + device.GetAddress()); } } } } }; private void Output(String text) { android.util.Log.d("ExampleTag", text); } } ``` {% endcode %} #### Device status callback subscription This callback provides information about the status of the card reader. It sends information about the initialization process of the device, the connection process of the card reader, and the mobile device. It also sends notifications about the actions expected by the user of the credit card. ```java 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.CardknoxPaymentEngineSDK; public class DeviceStatusExampleFragment 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_DeviceStatus, new IntentFilter(CardknoxPaymentEngineSDK.DEVICE_STATUS_INTENTFILTER_ACTION())); } } private void UnregisterIntentFilters() { Context c = this.getContext(); if(c != null) { c.unregisterReceiver(Receiver_DeviceStatus); } } private final BroadcastReceiver Receiver_DeviceStatus = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String action = intent.getAction(); // Verify that the Cardknox SDK broadcasted the event if(action.equals(CardknoxPaymentEngineSDK.DEVICE_STATUS_INTENTFILTER_ACTION())) { String extraKey = CardknoxPaymentEngineSDK.DEVICE_STATUS_INTENTFILTER_EXTRA(); String deviceStatus = intent.getStringExtra(extraKey); Output(deviceStatus); } } }; private void Output(String text) { android.util.Log.d("ExampleTag", text); } } ``` #### Transaction status callback subscription The transaction status callback sends information about the card scanning process. This callback starts triggering when the user inserts or swipes the credit card and ends with the result of card scanning. ```java 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.CardknoxPaymentEngineSDK; public class TransactionStatusExampleFragment 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_TransactionStatus, new IntentFilter(CardknoxPaymentEngineSDK.TRANSACTION_STATUS_INTENTFILTER_ACTION)); } } private void UnregisterIntentFilters() { Context c = this.getContext(); if(c != null) { c.unregisterReceiver(Receiver_TransactionStatus); } } private final BroadcastReceiver Receiver_TransactionStatus = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String action = intent.getAction(); // Verify that the Cardknox SDK broadcasted the event if(action.equals(CardknoxPaymentEngineSDK.TRANSACTION_STATUS_INTENTFILTER_ACTION())) { String extraKey = CardknoxPaymentEngineSDK.TRANSACTION_STATUS_INTENTFILTER_EXTRA(); String deviceStatus = intent.getStringExtra(extraKey); Output(deviceStatus); } } }; private void Output(String text) { android.util.Log.d("ExampleTag", text); } } ``` #### Result as JSON callback subscription The callback for a basic processed transaction response returns information about the transaction as an object with properties. Each property of the object corresponds to a specific piece of transaction data. However, the payment engine has an additional callback for the transaction result, which is returned as JSON. In this callback, instead of returning the transaction as an object, the processed transaction is provided as a text representation of a JSON object. To receive the transaction response as JSON using this callback, you must call the `SetSendResponseAsJSON(true)` method on `CardknoxPaymentEngineSDK`object . Otherwise, the transaction result will return the response as an object. The transaction response can only be received through a single callback at any given time. This means that only one callback handler is allowed to process the response for a specific transaction, ensuring consistency and avoiding potential conflicts or duplicate processing. ```java import android.content.BroadcastReceiver; import android.content.Context; import android.content.Intent; import android.content.IntentFilter; import androidx.fragment.app.Fragment; import cardknox.payments.sdk.CardknoxPaymentEngineSDK; import cardknox.payments.sdk.CardknoxPaymentEngineSDKRequest; import cardknox.payments.sdk.CardknoxPaymentEngineSDKResponseJSON; import cardknox.payments.sdk.CardknoxPaymentEngineSDKSettings; import cardknox.payments.sdk.CardknoxSDK; public class PaymentEngineExampleFragment extends Fragment { private void SetupReceivePaymentEngineResponseAsJSON(){ Context applicationContext = null; CardknoxSDK.create().getPaymentEngine().SetSendResponseaAsJSON(true); try { applicationContext.unregisterReceiver(Result_PaymentEngineResponseAsJSON);} catch(Exception e) {} applicationContext.registerReceiver(Result_PaymentEngineResponseAsJSON, new IntentFilter(CardknoxPaymentEngineSDK.PAYMENTENGINE_JSON_INTENTFILTER_ACTION())); } private final BroadcastReceiver Result_PaymentEngineResponseAsJSON = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String action = intent.getAction(); // Verify that the Cardknox SDK broadcasted the Intent if (action != null && action.equals(CardknoxPaymentEngineSDK.PAYMENTENGINE_JSON_INTENTFILTER_ACTION())) { String extraKey = CardknoxPaymentEngineSDK.PAYMENTENGINE_JSON_INTENTFILTER_EXTRA(); java.lang.Object extra = intent.getParcelableExtra(extraKey); // Cast CardknoxPaymentEngineSDKResponseJSON response = (CardknoxPaymentEngineSDKResponseJSON) extra; String json = response.GetJSON(); } } }; private void SetupPaymentEngineBroadcastsLogCatMessages(){ Context context = null; CardknoxPaymentEngineSDK paymentEngine = CardknoxSDK.create().getPaymentEngine(); // PaymentEngine logging, 2 options: // 1. SDK writes the PE log to LogCat directly // 2. SDK sends the PE log it wants to write to this app (via BroadcastReceiver) // Note: calling 1 method negates the other one boolean broadcast = false; boolean writeDirectly = true; if(broadcast && writeDirectly) throw new RuntimeException("PE logs can either be directly written to LogCat or broadcasted back to this app, not both"); if(writeDirectly){ paymentEngine.enableLogCatOutput("LogCatTag"); } else if(broadcast){ paymentEngine.enableLogCatBroadcasts(true); // subscribe to logcat broadcasts try { context.unregisterReceiver(Receiver_LogcatMessages);} catch(Exception e) {} context.registerReceiver(Receiver_LogcatMessages, new IntentFilter(CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_ACTION())); } } private final BroadcastReceiver Receiver_LogcatMessages = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { if(intent != null) { String action = intent.getAction(); if (action != null && action.equals(CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_ACTION())) { String logcatMessage = "unknown"; String extraKey= CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_EXTRA(); if(intent.hasExtra(extraKey)) logcatMessage = intent.getStringExtra(extraKey); android.util.Log.d("SomeTag", logcatMessage); } } } }; private void Device_ReprintReceipt_Example(){ CardknoxPaymentEngineSDKSettings settings = new CardknoxPaymentEngineSDKSettings(); settings.SetDevice_IP_Address("specify IP"); settings.SetDevice_IP_Port("specify port"); settings.SetDevice_Name("specify device name, such as PAX_A77.3"); settings.SetDevice_Timeout(5 * 1000); /* milliseconds to seconds */ CardknoxPaymentEngineSDKRequest request = new CardknoxPaymentEngineSDKRequest(); request.SetxAuthCode("add auth code here"); String response = CardknoxSDK.create().getPaymentEngine().Device_ReprintReceipt(settings, request); boolean success = response.equals("OK"); } } ``` #### Payment engine LogCat logging callback subscription LogCat callback logging is a feature that allows the payment engine to send log messages directly to the application through callbacks. When enabled—by setting the `EnableLogcatBroadcasts` property to true—the app receives log events programmatically instead of relying only on the standard LogCat console output. This method gives developers more control over how logs are used. Logs can be captured, filtered, stored, or forwarded to external monitoring systems, making it especially useful in production environments where console access is limited. It also enables building custom logging tools within the app for advanced debugging and diagnostics. ```java import android.content.BroadcastReceiver; import android.content.Context; import android.content.Intent; import android.content.IntentFilter; import androidx.fragment.app.Fragment; import cardknox.payments.sdk.CardknoxPaymentEngineSDK; import cardknox.payments.sdk.CardknoxPaymentEngineSDKRequest; import cardknox.payments.sdk.CardknoxPaymentEngineSDKResponseJSON; import cardknox.payments.sdk.CardknoxPaymentEngineSDKSettings; import cardknox.payments.sdk.CardknoxSDK; public class PaymentEngineExampleFragment extends Fragment { private void SetupPaymentEngineBroadcastsLogCatMessages(){ Context context = null; CardknoxPaymentEngineSDK paymentEngine = CardknoxSDK.create().getPaymentEngine(); // PaymentEngine logging, 2 options: // 1. SDK writes the PE log to LogCat directly // 2. SDK sends the PE log it wants to write to this app (via BroadcastReceiver) // Note: calling 1 method negates the other one boolean broadcast = false; boolean writeDirectly = true; if(broadcast && writeDirectly) throw new RuntimeException("PE logs can either be directly written to LogCat or broadcasted back to this app, not both"); if(writeDirectly){ paymentEngine.enableLogCatOutput("LogCatTag"); } else if(broadcast){ paymentEngine.enableLogCatBroadcasts(true); // subscribe to logcat broadcasts try { context.unregisterReceiver(Receiver_LogcatMessages);} catch(Exception e) {} context.registerReceiver(Receiver_LogcatMessages, new IntentFilter(CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_ACTION())); } } private final BroadcastReceiver Receiver_LogcatMessages = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { if(intent != null) { String action = intent.getAction(); if (action != null && action.equals(CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_ACTION())) { String logcatMessage = "unknown"; String extraKey= CardknoxPaymentEngineSDK.LOGGER_INTENTFILTER_EXTRA(); if(intent.hasExtra(extraKey)) logcatMessage = intent.getStringExtra(extraKey); android.util.Log.d("SomeTag", logcatMessage); } } } }; } ``` ### Out of scope integration Out of scope processing feature allows the developer to show the Cardknox user interface for payment processing. To show the user interface, create a request object that is capable of showing a user interface: ```javascript // 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: ```javascript 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 | Yes | No | | true | false | No | Yes | | false | true | Yes | No | | true | true | Yes | Yes |Example 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
Reference: Transaction API
| #### Pre processing options Developer using the Out Of Scope integration to process using the VP3300 card reader can specify a per-request transaction timeout value. The SDK will start a transaction with the VP3300 reader, and timeout in the specified time frame if the card is not tapped, swiped or inserted in that same time frame.| Function/property | Description | Sample data |
| VP3300TransactionTimeout | Start transaction value, in seconds. | |
Globally configures the SDK to auto close the user interface after processing a transaction.
Default value is false.
| CardknoxSDKUI.SetCloseSDKUIOnProcessedTransaction(false); |Example of a success popup.
Example of an error popup.
| Function | Description | Sample data |
| StartScanningWithTimeout | Starts the “scan for nearby bluetooth devices” process. If the timeout value is 0 or a negative number, the scanning never times out.
| |
| StopScanning | Attempts to stop the bluetooth device scanning process. Raises a “stop scan” card reader event. Doesn’t do anything if scanning is not in progress. If the method stops the scanning process, the SDK reports all scanned devices via a callback. | |
| 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:
| |
| ConnectWithAddress | Accepts a MAC address. Configures the SDK to be ready to establish a Bluetooth connection with the nearby VP3300 device with the internal MAC address equal to the provided value. | |
| DisconnectFromCurrentDevice | Attempts to break the connection between the application & the card reader. Otherwise, the SDK attempts to disconnect the card reader. If successful, the “disconnected” card reader event is raised. | |
| 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. | |
| 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. | |
The SetVP3300StartTransactionMethod function is a method of the TransactionParameters object used to configure how a card reader initiates a card transaction. It accepts a parameter of type VP3300StartTransactionMethod, which defines the scanning method the card reader should use.
By calling this method, developers can control the specific way in which the reader should prompt and process a card during a transaction, depending on the desired input method.
|The VP3300StartTransactionMethod parameter is an enumerated type that supports the following constant values:
CTLS– Contactless card transactionEMV– Chip (contact) card transactionMSR– Magnetic stripe card transactionDEVICE– Default or device-specific scanning behaviour.
TransactionParameters prms = new TransactionParameters(); prms.SetVP3300StartTransactionMethod(VP3300StartTransactionMethod.MSR); CardknoxSDK.create().getCustomUIUSB().startTransactionWithArgs(prms);
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.
Developers can override this value via the “parameters” object.
| `TransactionParameters prms = new TransactionParameters(); prms.SetxAmount(1.23); prms.SetxInvoice("1234"); prms.SetxCommand("cc:sale"); prms.SetVP3300TransactionTimeout(13); CardknoxSDK.create().getCustomUIUSB().startTransactionWithArgs(prms);` | | CancelTransaction |Attempts to cancel an already started transaction between the application & the card reader.
If no transactions are started when this function is called, the function does not do anything.
| `CardknoxSDK.create().getCustomUIUSB().cancelTransaction();` | #### Available commands Any of the following credit card commands are available for Custom UI: * cc:save * cc:credit * cc:authonly * cc:sale Reference: [Credit Card](/api/transaction/credit-card.md) #### 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 address”. Device name or the MAC address can be obtained with the “scan for devices” flow. Initiate the “start scanning” function call, with or without a timeout.Start scanning flow
Stop scanning flow
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.
| `CardknoxPaymentEngineSDKSettings settings = new CardknoxPaymentEngineSDKSettings(); settings.SetDevice_IP_Port("9001"); settings.SetDevice_IP_Address("127.21.2.7"); settings.SetDevice_Name("Verifone_P400.4"); settings.SetDevice_Timeout(120 * 1000); // 120 seconds; CardknoxSDK.create().getPaymentEngine().Device_Initialize(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.
| `CardknoxPaymentEngineSDKSettings settings = new CardknoxPaymentEngineSDKSettings(); settings.SetDevice_IP_Port("9001"); settings.SetDevice_IP_Address("127.21.2.7"); settings.SetDevice_Name("Verifone_P400.4"); settings.SetDevice_Timeout(120 * 1000); // 120 seconds; CardknoxPaymentEngineSDKRequest request = new CardknoxPaymentEngineSDKRequest(); request.SetxCommand("cc:sale"); request.SetxAmount(1.23); CardknoxSDK.create().getPaymentEngine().ProcessOutOfScope(settings, 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.
| `CardknoxSDK.create().getPaymentEngine().Device_CancelTransaction();` | | SetSendResponseaAsJSON | This function configures the SDK for Payment Engine integration. When the value is set to `true`, the SDK returns a processed transaction response via the [Result as JSON callback](https://cardknox.atlassian.net/wiki/spaces/MOB/pages/2661711873/Android+SDK+User+Manual#Result-as-JSON-callback-subscription). Otherwise, the transaction response is provided through the basic [Transaction Result callback](https://cardknox.atlassian.net/wiki/spaces/MOB/pages/2661711873/Android+SDK+User+Manual#Transaction-result-callback-subscription). | `CardknoxSDK.create().getPaymentEngine().SetSendResponseaAsJSON(true);` | | EnableLogcatBroadcasts | The EnableLogcatBroadcasts property enables log delivery via callbacks. When set to true, the payment engine sends logs to the app instead of just printing them to the LogCat console, allowing custom handling of log messages. | `CardknoxSDK.create().getPaymentEngine().enableLogCatBroadcasts(true);` | | Device\_ReprintReceipt | This method is used to reprint a transaction receipt from the card reader. This function allows users to reprint receipts for any previous transaction. It is useful in situations where a receipt was not printed correctly, was lost, or when a customer requests a duplicate or previous transaction receipt | `CardknoxPaymentEngineSDKSettings settings = new CardknoxPaymentEngineSDKSettings(); settings.SetDevice_IP_Address("specify IP"); settings.SetDevice_IP_Port("specify port"); settings.SetDevice_Name("specify device name, such as PAX_A77.3"); settings.SetDevice_Timeout(5 * 1000); /* milliseconds to seconds */ CardknoxPaymentEngineSDKRequest request = new CardknoxPaymentEngineSDKRequest(); request.SetxAuthCode("add auth code here"); String response = CardknoxSDK.create().getPaymentEngine().Device_ReprintReceipt(settings, request); boolean success = response.equals("OK");` | ### Versioning Developers can read from the `cardknox.payments.sdk.BuildConfig` class, properties are: | `VERSION_NAME` | Major SDK version | | -------------- | --------------------------------------- | | `VERSION_CODE` | Release number in the major SDK version | | `GIT_HASH` | Git tag for troubleshooting | ### Logging SDK verbose logging can be enabled or disabled with a function call: | **Function** | **Description** | **Sample data** | | ------------- | -------------------------------------------------------------------- | --------------------------------- | | EnableLogging |Accepts a boolean.
Enables or disables verbose logging.
| CardknoxSDK.enableLogging(false); | ### FAQ 1. As a Cardknox SDK user, I want to process without an internet connection. What will happen? * The SDK will return a `PaymentTransactionResponse` object with a special `xErrorCode` value `-1` 2. As a Cardknox SDK user, I’ve encountered errors during transaction processing. What response can I expect? * the `PaymentTransactionRequest` object will encapsulate all relevant information in respective fields; for example the `xErrorCode` property will return a code from the Cardknox Transaction API documentation, the `xErrorMessage` and `xError` properties can be used for a descriptive error message while the `xRefNum` gives back a unique ref num to follow up with the customer support --- # 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/android-sdk.md?ask=