Set Properties

There are no additional requirements around the setProperties method required to run Tap
To Mobile transactions beyond the usual:

API Key
Application Identifier
Environment
External Device Info (if applicable)

Method Calls

Get Status

The getStatus method provides detailed information about the current status of the Payment Device SDK and the configured payment environment. It has been updated to include additional response parameters.

BEHAVIOR

The getStatus method now returns identifiers that distinguish between the configured payment methods. These identifiers are crucial for integration with NMI’s payment gateway and for troubleshooting specific device-related issues.

NEW RESPONSE PARAMETERS

ParameterKeys.POSGUID
- An identifier representing the Point of Sale Device. This value is used to identify the Point of Sale with NMI’s payment gateway.
ParameterKeys.TapToMobilePOIIdentifier
- An identifier representing the Tap To Mobile Point of Interaction. This value is used to identify this instance of Tap To Mobile to NMI’s payment gateway.

RECOMMENDATION

It’s highly recommended to make this identifier accessible to application users to facilitate troubleshooting for specific devices.

Method API Doc

Parameters:
requestParameters - Parameters collection which can contain the following:

ParameterKeys.PaymentPlatformTest (Optional) With a value of ParameterValues.TRUE, this will
check the status of the payment platform, returning the result in a PaymentPlatformStatus object in the
response.

Returns:
Parameter collection containing the following:

ParameterKeys.Result Defines if the call to getStatus was successful using the values
ParameterValues.TRUE and ParameterValues.FALSE.

ParameterKeys.VersionInformation An XML representation of a VersionInformation object.
ChipDnaMobileSerializer.deserializeVersionInformation(String) can be used to retrieve an
object.

ParameterKeys.ChipDnaStatus A string representing the current status of ChipDNA Mobile.

ParameterKeys.DeviceStatus An XML representation of a DeviceStatus object.
ChipDnaMobileSerializer.deserializeDeviceStatus(String) can be used to retrieve an object.

ParameterKeys.TmsStatus An XML representation of a TmsStatus object.
ChipDnaMobileSerializer.deserializeTmsStatus(String) can be used to retrieve an object.

ParameterKeys.TerminalStatus An XML representation of the live TerminalStatus.
ChipDnaMobileSerializer.deserializeTerminalStatus(String) can be used to retrieve an object.

ParameterKeys.Environment The current environment ChipDNA Mobile is running in. Will have a value of either ParameterValues.LiveEnvironment or ParameterValues.TestEnvironment.

ParameterKeys.RequestQueueStatus An XML representation of a RequestQueueStatus object. ChipDnaMobileSerializer.deserializeRequestQueueStatus(String) can be used to retrieve an object.

ParameterKeys.PaymentPlatformStatus An XML representation of a PaymentPlatformStatus object. ChipDnaMobileSerializer.deserializePaymentPlatformStatus(String) can be used to
retrieve an object.

ParameterKeys.LinkedRefundsSupported When present with the value ParameterValues.TRUE, this indicates that linked refunds are supported with the currently configured terminal.

ParameterKeys.CashTransactionsSupported When present with the value ParameterValues.TRUE, this indicates that cash transactions are supported with the currently configured terminal.

ParameterKeys.ChequeTransactionsSupported When present with the value
ParameterValues.TRUE, this indicates that cheque transactions are supported with the currently configured terminal.

ParameterKeys.TransactionHistorySupported When present with the value
ParameterValues.TRUE, this indicates that transaction history is supported with the currently configured terminal.

ParameterKeys.EmailReceiptSupported When present with the value ParameterValues.TRUE, this
indicates that centralized email receipting is supported with the currently configured terminal.

ParameterKeys.SmsReceiptSupported When present with the value ParameterValues.TRUE, this indicates that centralized SMS receipting is supported with the currently configured terminal.

ParameterKeys.RefundOperatorPinSupported Indicates that an operator PIN must be supplied to perform standalone refunds with the currently configured terminal if present with the value ParameterValues.TRUE.

ParameterKeys.OfflineProcessingSupported When present with the value
ParameterValues.TRUE, this indicates that offline transaction processing is supported with the currently
configured terminal.

ParameterKeys.TippingSupported Indicates the type of tipping supported with the currently
configured terminal. Values can be:
- ParameterValues.EndOfDayTipping
- ParameterValues.OnDeviceTipping
- ParameterValues.BothTipping

ParameterKeys.ApplicationIdentifier A string representing the current identifier for the application.

ParameterKeys.MerchantDisplayName Indicates the currently configured merchant display name, if present.

ParameterKeys.PinPadName Indicates the currently configured PINpad name, if present.

ParameterKeys.PinPadConnectionType Indicates the currently configured PINpad connection type, if present.

ParameterKeys.PinPadIpAddress Indicates the currently configured PINpad IP address, if present.

ParameterKeys.PinPadPort Indicates the currently configured PINpad port, if present.

ParameterKeys.FirmwareUpdateAvailable Indicates whether a firmware update is available for the
currently configured PINpad.

ParameterKeys.FirmwareUpdateStatus An XML representation of a FirmwareUpdateStatus object.
ChipDnaMobileSerializer.deserializeFirmwareUpdateStatus(String) can be used to retrieve
the object.

ParameterKeys.POSGUID A string representing the current point of sale globally unique identifier.

ParameterKeys.TapToMobilePOIIdentifier A string representing the current TTM point of
interaction identifier.

Connect and Configure

The connectAndConfigure method enables the setup and configuration of both Tap To
Mobile and external payment devices. The behavior of this method is determined by the
parameters provided during the call.

REQUIRED PARAMETERS FOR TAP TO MOBILE

ParameterKeys.TapToMobilePOI
- Value : ParameterValues.TRUE

This parameter must be included to trigger the configuration of Tap To Mobile.

PARAMETERS FOR PAYMENT DEVICE CONFIGURATION

ParameterKeys.PaymentDevicePOI
- Value : ParameterValues.TRUE This value enables the Payment Device SDK to configure and use an external payment device for transactions.
- Value : ParameterValues.FALSE This value prevents the Payment Device SDK from attempting to configure an external payment device, enabling a Tap To Mobile-only environment.

BEHAVIOR

Tap To Mobile-Only Environment
- Include ParameterKeys.TapToMobilePOI with a value of ParameterValues.TRUE
- Include ParameterKeys.PaymentDevicePOI with a value of ParameterValues.FALSE This configuration stops the Payment Device SDK from attempting to set up an external payment device.
Tap To Mobile and Payment Device Environment
- Include ParameterKeys.TapToMobilePOI with a value of ParameterValues.TRUE
- Include ParameterKeys.PaymentDevicePOI with a value of ParameterValues.TRUE This configuration enables the use of both Tap To Mobile and external payment devices.
Default Payment Device Behavior
- If no POI Parmamer key is provided, the SDK will default to enabling the external payment device.

USER AGREEMENT REQUIREMENT

During the initial configuration of Tap To Mobile, the user will be prompted to accept Apple’s
Tap To Pay agreement.

Note: This prompt occurs only the first time a unique device and user combination is used.

Method API Doc

Parameters:
requestParameters - Parameters collection which can contain the following:

ParameterKeys.ForceTmsUpdate Force connectAndConfigure to perform a TMS update whether
one is required or not.

ParameterKeys.FullTmsUpdate Force a full TMS update whether one is required or not. All
configuration will be downloaded regardless of whether it's required.

ParameterKeys.BLEScanTime (Optional) Set the length of time to scan for Bluetooth Low Energy
(BLE) devices. The value is required to be a string valued number between 1 and 30. The default value
of 5 seconds will be used if this value is not available.

ParameterKeys.ApplyFirmwareUpdate (Optional) When present with the value
ParameterValues.FALSE, this stops a firmware update beginning, if one is available.

ParameterKeys.PaymentDevicePOI (Optional) Sets if the Payment Device point of interaction is
to be configured for payment processing. Values can be ParameterValues.TRUE or
ParameterValues.FALSE. (Defaults to ParameterValues.TRUE if the parameter key is not
present).

ParameterKeys.TapToMobilePOI (Optional) Sets if the Tap To Mobile point of interaction is to
be configured for payment processing. Values can be ParameterValues.TRUE or
ParameterValues.FALSE. (Defaults to ParameterValues.FALSE if the parameter key is not
present).

Returns:
A parameter collection which can contain:
ParameterKeys.Result
ParameterKeys.Errors

Start Transaction

The startTransaction method allows you to specify the type of payment to be performed during a transaction. A new parameter key has been introduced to facilitate this:

NEW PARAMETER KEY

ParameterKeys.TransactionPOI: This parameter determines the transaction point of interaction to be used.

ACCEPTED PARAMETER VALUES

ParameterValues.PaymentDevice: Specifies the use of a physical payment
device for the transaction.
ParameterValues.TapToMobile: Specifies the use of the Tap To Mobile
functionality for the transaction.

BEHAVIOR

Single Transaction POI Configured
If only one transaction POI is configured (either Payment Device or Tap To Mobile), it
will be automatically selected when starting a transaction.
Both Transaction POI’s Configured
If both Payment Device and Tap To Mobile are configured, the payment device will be
used by default unless the Transaction POI parameter explicitly specifies Tap To
Mobile.

Method API Doc

Parameters:
requestParameters - Parameters collection which can contain the following:

ParameterKeys.Amount (Required) The amount to be used in the transaction.

ParameterKeys.userReference (Required) A unique reference for this transaction.

ParameterKeys.TransactionType (Required) The transaction type for this transaction. Values
can be ParameterValues.Sale or ParameterValues.Refund or
ParameterValues.AccountVerification.

ParameterKeys.Currency Set the currency for this transaction. Only required when
ChipDnaMobile.getAvailableCurrencies(Parameters)returns more than one currency. If only a single currency is supported, it will be used by default.

ParameterKeys.PANKeyEntry Requests a PAN Key Entry transaction is started for a card not
present transaction. Values can be ParameterValues.TRUE or ParameterValues.FALSE.

ParameterKeys.DelayOnlineProcessing Requests that online processing is delayed. Values can
be ParameterValues.TRUE or ParameterValues.FALSE. In this case the transaction will process
to the point of going online and then return a EncodedRequest to the registered
ITransactionFinishedListener.

ParameterKeys.PaymentMethod Specifies the payment method being used for this transaction.
Values can be ParameterValues.Card, ParameterValues.Cash or
ParameterValues.Cheque.

ParameterKeys.CredentialOnFileFirstStore (Optional) Flags the transaction as the first
store for a Credential on File transaction when the value is ParameterValues.TRUE.

ParameterKeys.CredentialOnFileReason (Optional) Indicates the reason for a Credential on
File transaction. Only considered if the value for ParameterKeys.CredentialOnFileFirstStore
is ParameterValues.TRUE. Values can be:

- ParameterValues.ReasonUnscheduled
- ParameterValues.ReasonInstallment
- ParameterValues.ReasonIncremental
- ParameterValues.ReasonResubmission
- ParameterValues.ReasonDelayedCharge
- ParameterValues.ReasonReAuth
- ParameterValues.ReasonNoShow

ParameterKeys.OnDeviceTippingPrompt (Optional) Sets a custom tipping prompt for on-device tipping. Only supported on Miura M020 and M021 PIN pads.

ParameterKeys.DynamicTippingAmounts (Optional) or
ParameterKeys.DynamicTippingPercentages (Optional) Enables on-device dynamic tipping using the provided amounts or percentages. Only one of the amount types can be used in a request.
Dynamic tipping is currently only supported on Miura M020 and M021 PIN pads.

ParameterKeys.DynamicTippingheader (Optional) Sets the header for the dynamic tipping
screen. This is only supported if dynamic tipping is enabled.

ParameterKeys.AutoConfirm (Optional) Sets if auto confirmation of a transaction should
happen. Values can be ParameterValues.TRUE or ParameterValues.FALSE. The default value
is ParameterValues.FALSE, unless processing via Tap To Mobile, where the default value is
ParameterValues.TRUE and ParameterValues.FALSE will not be accepted.


ParameterKeys.TransactionPOI (Optional) Sets the transaction point of interaction to be used
for this transaction. If one POI has been configured via ChipDnaMobile.connectAndConfigure,
then this will be the default value, if one is not present. If multiple POI have been configured, then the
default value will be ParameterValues.PaymentDevice, if the parameter key is not present. Can
be one of the following values:

- ParameterValues.PaymentDevice
- ParameterValues.TapToMobile

Returns:
A parameter collection which can contain:
ParameterKeys.Result
ParameterKeys.Errors

Starting A Transaction

This section describes the parameters required for a Tap To Mobile transaction, the
parameters that will cause errors if used, and the parameters returned in a transaction
finished event.

PARAMETERS REQUIRED FOR A TAP TO MOBILE TRANSACTION

The following parameters are required to start a TTM transaction:

ParameterKeys.Amount
ParameterKeys.UserReference
ParameterKeys.PaymentMethod
- Must be set to ParameterValues.Card.
ParameterKeys.TransactionType
- Must be set to ParameterValues.Sale.

PARAMETERS THAT WILL CAUSE ERRORS FOR A TAP TO MOBILE TRANSACTION

Tap To Mobile currently only supports auto confirmed sale transactions therefore the
following parameters will return an error if included when starting a Tap To Mobile
transaction:

ParameterKeys.TransactionType
- ParameterValues.Refund
- ParameterValues.AccountVerification
ParameterKeys.DelayOnlineProcessing
- ParameterValues.TRUE
ParameterKeys.PANKeyEntry
- ParameterValues.TRUE
ParameterKeys.TippingType
- ParameterValues.OnDeviceTipping
- ParameterValues.EndOfDayTipping
- ParameterValues.BothTipping
ParameterKeys.AutoConfirm
- ParameterValues.FALSE

Events

Connect And Configure Events

This section describes the events returned by the SDK during operation of Tap To Mobile, including those for the connectAndConfigure process, error codes, and transaction
events.

CONFIGURATIONUPDATE

The following new events are emitted during the connectAndConfigure process:

CheckingTapToMobileConfig indicates that the Payment Device SDK is checking the current configuration of Tap To Mobile.

UpdatingTapToMobileConfig Indicates that the Payment Device SDK is updating its
Tap To Mobile Configuration.

TapToMobileConfigurationPercentage indicating the percentage of the configuration
process for Tap To Mobile. Value is an integer between 0 and 100.

Note: UpdatingPinPadConfig is still available and used to indicate the Payment Devices config is being updated

Transaction Events

TRANSACTIONFINISHED

The following parameters, if available, will be returned in a transaction finished event for a
Tap To Mobile transaction:

ParameterKeys.UserReference
ParameterKeys.TransactionResult
ParameterKeys.Amount
ParameterKeys.AuthCode
ParameterKeys.AcquirerResponseCode
ParameterKeys.TransactionDateTime
ParameterKeys.DateTimeFormat
ParameterKeys.CardSchemeId
ParameterKeys.MaskedPan
ParameterKeys.TransactionType
ParameterKeys.Currency
ParameterKeys.ReceiptData
ParameterKeys.PreformattedMerchantReceipt
ParameterKeys.PreformattedCustomerReceipt
ParameterKeys.Errors
ParameterKeys.CardReference
ParameterKeys.CardHashCollection
ParameterKeys.PAR
ParameterKeys.CardSchemeID

New Error Codes

This section details the new error codes added as part of Tap To Mobile. A full list of error
codes can be viewed within the generated web documentation supplied within the release
bundles docs directory. Navigate to index.html then under Modules >
ChipDnaMobileErrorCodes.

CONNECT AND CONFIGURE

The following new error codes may be returned when calling connectAndConfigure.

TapToMobileNotSupported: Indicates that the current hardware does not support
Tap To Mobile payment processing.
NoPoiSelected: Indicates that no point of interaction was selected for
configuration.
LocationPermissionsNotGranted: Indicates that the application does not have
location permissions granted, which are required for Tap To Mobile payment
processing.
ApplicationUpdateRequired: Indicates that the CloudCommerce SDK being used is now too old and an update is required. This can be for the following reasons:
- Pinned certificate rotation: The SDK embeds a certificate for communication with the Mastercard server. If this certificate is rotated, then an update of the SDK would be done, and an updated version of the Cloud Commerce iOS SDK would be released. In such cases this will be a forced upgrade as the older SDK would cease to work due to expiration of the said certificate.
- Support for Proximity Reader Framework functionality: In the event Apple changes the framework (adds or depreciates functionality) or the API’s, this would not be a forced upgrade as the older version of the SDK would still work without this upgrade.
- Changes in attestation: If any change to the attestation services or updates by Apple occur, then an updated version of the CloudCommerce iOS SDK would be released.

CONNECT AND CONFIGURE FINISHED EVENT

The following new error codes may be returned in the connectAndConfigureFinished
event.

CountryCodeInvalid: Indicates an error with the country code being used for Tap
To Mobile.
AttestationFailed: Indicates that the attestation process for Tap To Mobile has
failed.
AccessTokenExpired: The Tap To Mobile session token has expired. You may need to call performTmsUpdate()
TeamIdentifierMissing: Tap To Mobile was unable to locate your team identifier. This should be added to your info.plist as described above.
InvalidAppleAccount:The current apple account being used on the device is invalid or can’t be used to support Apple Tap To Pay. In development ensure you’re logged in to an Apple Sandbox account.
MissingBundleIdentifier: Tap To Mobile was unable to find a bundle identifier that can perform Tap To Pay transactions. Ensure your entitlements are correctly linked and the bundle identifier matches the one in your application.
CurrentCountryNotAllowed: The country of your merchant account doesn’t match the location you’re attempting to perform a transaction in.
NoLocationFound: Tap To Mobile was unable to determine your location. Ensure your location permissions are correctly set.

START TRANSACTION

The following new error codes may be returned during calls to startTransaction.

TransactionPOINotConnected: Indicates that the transaction point of interaction
attempting to be used is not connected.
TransactionPOIInvalid: Indicates that the transaction point of interaction being
used is invalid.
AutoConfirmRequired: Indicates that the transaction requires auto-confirmation.
TipAmountInvalid: The tip amount supplied to start transaction isn’t in a valid format
TipAmountNotAllowed: Merchant Tipping is not supported for this TransactionPOI
MerchantTippingNotSupported:Tipping via Merchant Tipping is not supported with the configured processor.

TRANSACTION FINISHED EVENT

The following new error codes may be returned in the transactionFinished event.

TapToMobileTransactionTerminated: Indicates that the transaction was
terminated by Tap To Mobile.
TapToMobileSessionClosed: Indicates that the current Tap To Mobile Session is
no longer available.