Parameters

The request and response data in the Payment Device SDK API methods is set in a Parameters object. The Parameters object is a collection of name-value pairs representing the data sent to or received from the SDK.

Initialization

Parameters initialize(Context, Parameters)
Your application interacts with the Payment Device SDK using a method in the ChipDnaMobile object instance. Before beginning the messaging process, you must initialize a new ChipDnaMobile instance.

This method returns a Parameters object with the result of the initialization. Any errors encountered will also be reported in this object.

SetProperties

Parameters setProperties(Parameters)
Call setProperties() to set configuration settings for the Payment Device SDK. This method is synchronous and results are returned in the parameters.

setProperties() Is also used in the SDK to set:

• API Key
• Application Identifier
• PIN pad name

ConnectAndConfigure

Parameters connectAndConfigure(Parameters)
After initialization and the correct properties are set, a call to this method will connect to the PIN pad and if needed downloads configuration data from TMS and configures the device in preparation for performing transactions.

When the connectAndConfigure() method call is successful, asynchronous updates are provided in the configurationUpdate and configureAndConnectFinished callbacks.

The connectAndConfigure() can also be used to perform a TMS update by including the ForceTmsUpdate parameter with a value of TRUE.

The connectAndConfigure() can also be used to perform a Firmware update. To control when an update occurs include the ApplyFirmwareUpdate parameter. If no parameter is supplied it will default to applying a firmware update straight away if new firmware is available. With a value of FALSE it can be delayed until an update is critical, a time frame 16 defined in FirmwareUpdateConfiguration TMS property. When an update is critical, connectAndConfigure() will fail with a FirmwareUpdateRequired error code. This firmware update control feature is currently only supported on ID TECH VP3350 PIN pads on iOS, where an update is automatically applied if available for all other PIN pads.

GetAvailablePinPads

Parameters getAvailablePinPads(Parameters)
Call getAvailablePinPads() for the Payment Device SDK to search for available PIN pads.

getAvailablePinPads() is asynchronous. The results of the PIN pad search will be provided in the onAvailablePinPads callback.

The request parameters can be used to indicate which communication protocol to use (e.g., in Android it is possible to search for PIN pads on Bluetooth Classic, Bluetooth Low Energy (BLE), USB or any combination of communication protocols.)

The length of time that the SDK will scan for BLE devices is customizable. Increasing the Bluetooth Low Energy scanning time will result in a higher likelihood of the BLE device being discovered.

GetStatus

Parameters getStatus(Parameters)
Call getStatus() to get the current status of different components of the Payment Device SDK in a single call. If no parameters are specified, the status of all the different components is checked. The request parameters can be used to specify which components need to be checked.

getStatus() is a synchronous method which will block and return the requested status data in the response parameters. Information returned includes offline queue status, current properties, the SDK version, firmware update status, payment device information, and payment platform availability.

GetTransactionInformation

Parameters getTransactionInformation(Parameters)
Call getTransactionInformation() to get the current information corresponding to the specified transaction. This information includes, among other items, the transaction result, transaction time, whether it has been confirmed or not.

GetMerchantData

Parameters getMerchantData(Parameters)
Call getMerchantData() to get the current information corresponding to the configured merchant accounts. This information includes, the currencies supported, transaction types supported and the merchant’s name and number.

RequestTmsUpdate

Parameters requestTmsUpdate(Parameters)
Use requestTmsUpdate() to force an immediate TMS update.

requestTmsUpdate() is not required as part of the normal workflow as ConnectAndConfigure will automatically perform a TMS update. This method requires a connection to the PIN pad to be established before it can be called.

The requestTmsUpdate() can also be used to perform a Firmware update. To control when an update occurs include the ApplyFirmwareUpdate parameter. If no parameter is supplied it will default to applying a firmware update straight away if new firmware is available. With a value of FALSE it can be delayed until an update is critical, a time frame defined in FirmwareUpdateConfiguration TMS property. When an update is critical, it will prevent actions requiring the PIN pad to be performed, these are startTransaction() and getCardDetails(). This firmware update control feature is currently only supported on ID TECH VP3350 PIN pads on iOS, where an update is automatically applied if available for all other PIN pads.

If requestTmsUpdate() method call is successful the result of the TMS update result is provided in the tmsUpdate event.

Disconnect

Parameters disconnect (Parameters)

Call this method to disconnect from any connected PIN pads.

Dispose

Parameters dispose(Parameters)
Call this method to dispose of the ChipDnaMobile instance. This will release resources including closing database connections and disconnecting from any connected PIN pads. After dispose() is called, initialize() must be called to use the Payment Device SDK again.