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

Android Specific Configuration for Tap to Pay

For Android Tap to Pay transactions, the setProperties() method requires the standard parameters plus one additional Android specific parameter:

Required Parameters

CertificateFingerprint Parameter

The CertificateFingerprint parameter is mandatory for Android Tap to Pay implementations:

• Format: SHA-256 hex string
• Source: Your Google Play app signing certificate
• Purpose: Used for app attestation and security verification

The certificate fingerprint can be found in your Google Play Console under Test and release > App signing. See the App Onboarding section for detailed instructions on obtaining this value.

Example Configuration

Parameters properties = new Parameters();
properties.add(ParameterKeys.ApiKey, "yourApiKey");
properties.add(ParameterKeys.ApplicationIdentifier, "yourAppIdentifier");
properties.add(ParameterKeys.Environment, ParameterValues.LiveEnvironment);
properties.add(ParameterKeys.CertificateFingerprint, "yourSha256HexString");

ChipDnaMobile.getInstance().setProperties(properties);

ConnectAndConfigure

Parameters connectAndConfigure(Parameters)
After initialization and the correct properties are set, a call to this method will connect to the PIN pad. If needed it will download 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.

Android Tap to Pay Configuration

The connectAndConfigure() method enables the setup and configuration of both Tap to Pay and external payment devices. The behavior is determined by the parameters provided during the call.

Required Parameters for Tap to Pay

• ParameterKeys.TapToMobilePOI with value ParameterValues.TRUE
  • This parameter must be included to trigger the configuration of Tap to Pay

Parameters for Payment Device Configuration

• ParameterKeys.PaymentDevicePOI
  • Value:ParameterValues.TRUE - enables external payment device configuration
  • Value:ParameterValues.FALSE - prevents external payment device setup (Tap to Pay only)

Configuration Modes

Tap to Pay Only Environment

Parameters params = new Parameters();
params.add(ParameterKeys.TapToMobilePOI, ParameterValues.TRUE);
params.add(ParameterKeys.PaymentDevicePOI, ParameterValues.FALSE);
ChipDnaMobile.getInstance().connectAndConfigure(params);

Tap to Pay and Payment Device Environment

Parameters params = new Parameters();
params.add(ParameterKeys.TapToMobilePOI, ParameterValues.TRUE);
params.add(ParameterKeys.PaymentDevicePOI, ParameterValues.TRUE);
ChipDnaMobile.getInstance().connectAndConfigure(params);

Default Behavior

If no POI parameter key is provided, the SDK will default to enabling the external payment device only.

Firmware Updates

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 is 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, where an update is automatically applied if available for all other PIN pads. To enable firmware update configuration feature please contact your Account Manager.

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.

Tap to Pay Enhanced Status

The getStatus() method has been updated to include additional response parameters that distinguish between configured payment methods. These identifiers are crucial for integration with NMI's payment gateway and for troubleshooting specific device related issues.

New Response Parameters

It's highly recommended to make these identifiers accessible to application users to facilitate troubleshooting for specific devices.

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, where an update is automatically applied if available for all other PIN pads. To enable firmware update configuration feature please contact your Account Manager.

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.