NFCMonitor

The NFCMonitor SPI is used for the SDK's internal monitoring. The MPP uses this SPI to detect the SDK's execution status.

Method signature

copy
public interface NFCMonitor {
    void track(String monitorId, Map<String, String> params);
}

Request parameters

Method	Item	Type	Description	Required
track	monitorId	String	The SDK's internal ID of the monitoring point.	Yes
track	params	Map<String, String>	A key-value object that contains the monitor fields of monitorId and their values. For details about monitoring points and their fields, see Monitor tracking points.	Yes

Monitor tracking points

Common fields

The following fields are automatically included in every monitor event. They are not repeated in the individual event tables below.

Field	Type	Description
sdkVersion	String	The version code of the SDK build.
os_version	String	The Android OS version of the device. Omitted when empty.
model	String	The model name of the device. Omitted when empty.
manufacturer	String	The manufacturer of the device. Omitted when empty.
manufacturer_os_version	String	The manufacturer-specific OS version of the device. Omitted when empty.

NFC card activation monitor

monitorId = EVENT_APPLY

This monitor reports the following data when the card activation process is completed.

Field	Type	Description
applyLoopTimeConsume	String	Total time spent for the card application polling.
activateLoopTimeConsume	String	Total time spent for the card activation polling.
applyTimeConsume	String	Total time spent for the card application process.
applyResult	String	The result of the card application process.
phase	Array<String>	The phases of the card application process. If the card application fails, you can locate the failing phase with this field.
isSilent	String	Indicates whether the card activation is in silent mode. Valid values are: `true`: Yes `false`: No
current_id	String	The unique ID to identify the current user connecting the SDK. The value of this field is generated when the app calls the connect API.
utdId	String	The user's device fingerprint.

Card activation confirmation monitor

monitorId = EVENT_CONFIRM

This monitor reports the following data when the card activation confirmation is completed.

Field	Type	Description
confirmResult	String	The result of card activation confirmation. Valid values are: `true`: Successful `false`: Failed
current_id	String	The unique ID to identify the current user.
tur	String	The unique ID assigned to identify a card.
errorCode	String	The error code associated with the failure. This field returns only when the confirmation fails.

replenish API monitor

monitorId = EVENT_REPLENISH

This monitor reports the following data when the replenish process is triggered.

Field	Type	Description
countCredential	String	The number of credentials issued by Mastercard. A value of `0` is reported by default if the replenishment process fails.
replenishResult	String	The result of the replenishment process. Valid values are: `true`: Successful `false`: Failed
tur	String	The unique ID assigned to identify a card.
errorCode	String	The error code associated with the failure. This field is returned if the replenishment process fails.
errorMsg	String	The error message associated with the failure. This field is returned if the replenish process fails.

Session rebuild monitor

monitorId = EVENT_SESSION

This monitor reports the following data when the SDK rebuilds a session with Mastercard Digital Enablement Service upon session expiration.

Field

Type

Description

sessionResult

String

The result of the session rebuilding process.

Valid values are:

true: Successful
false: Failed

errorCode

String

The error code associated with the failure.

This field is returned if the session rebuilding process fails.

SDK risk control time-consuming monitor

monitorId = EVENT_RISK

This monitor reports the following data when the SDK risk control process is completed.

Field

Type

Description

ret

String

The result of risk control evaluation.

Valid values are:

true: The risk is detected.
false: The risk is not detected.

risk_time

String

The time spent for the risk control evaluation.

SDK identity verification monitor

monitorId = EVENT_AUTH_POLICY

This monitor reports the following data when the SDK identity verification process is completed.

Field	Type	Description
secure_screen	String	Indicates whether the screen lock password is set. Valid values are: `true`: Set `false`: Not set
has_auth	String	Indicates whether the identity has been verified. Valid values are: `true`: Yes `false`: No
context_match	String	Indicates whether the transaction context changes in the double-tapping scenario. Valid values are: `true`: Changed `false`: Not changed
policy_time	String	Time spent for the policy evaluation.
biz_permit	String	The permission decision returned by the business side SPI. Valid values are: `true`: Permitted `false`: Declined
risk_sdk	String	Indicates whether the risk control SDK judgment has been initiated. Valid values are: `true`: Yes `false`: No
policy_type	String	The type of security policies. Valid values are: `ConsentPolicy`: The policy is related to user consent. `TransitPolicy`: The policy is related to transit transactions. `RiskJudgePolicy`: The policy is related to risk assessment and evaluation. `WithoutConsentPolicy`: No consent related policy is required.

Transaction monitor

monitorId = EVENT_TRANSACTION

This monitor reports the following data when the transaction is completed.

Field	Type	Description
ret	String	The result of the transaction. Valid values are: `true`: Successful `false`: Failed
transaction_time	String	The time spent for this transaction.
command_sum	String	The total time spent for executing all commands within the transaction.
command_i	String	The time taken to execute the command with sequence number `i`. In the standard MCBP interaction, `i` ranges from 0 to 8.
errorCode	String	The error code associated with the failure. This field is returned if the transaction fails.
current_id	String	The unique ID to identify the current user.
tur	String	The unique ID assigned to identify a card.

connect API time-consuming monitor

monitorId = EVENT_CONNECT

This monitor reports the following data when the MPP app calls the connect API.

Field	Type	Description
core_init_time	String	The time taken to initialize the SDK core.
connect_time	String	The total time spent for the connection.
cache_init_time	String	The time taken to initialize the SDK cache.
current_id	String	The unique ID used to identify the current SDK.
tur	String	The unique ID assigned to identify a card.

disconnect API monitor

monitorId = EVENT_DISCONNECT

This monitor reports the following data when the MPP app calls the disconnect API.

Field	Type	Description
current_id	String	The unique ID used to identify the current connection.

auth API monitor

monitorId = EVENT_AUTH

This monitor reports the following data when the MPP app calls the auth API.

Field

Type

Description

is_auth

String

Indicates whether to process authentication.

Valid values are:

true: Process authentication
false: Cancel authentication

Transaction information monitor

monitorId = EVENT_TRANSACTION_INFO

This monitor reports the following data when the transaction process is completed.

Field	Type	Description
mcc	String	The merchant category code (MCC).
type	String	The type of the transaction.
amount	String	The transaction amount.
merchant_name	String	The merchant name. Note: The value of this field returns in HEX encoding.
country_code	String	The terminal country code. Note: The value of this field returns in HEX encoding.
isDebitBin	String	Indicates whether the card is a debit card. Valid values are: `true`: Yes `false`: No
current_id	String	The unique ID to identify the current user.
customIAD	String	The customize data.
transit_check_advancepay_limit_switch	String	Indicates whether the advance pay limit check is enabled. Valid values are: `0`: Disabled `1`: Enabled
transit_advancepay_limit_status	String	The status of the advance pay limit returned from the server APIs. Valid values are: `0`: The payment amount is limited. `1`: The payment amount is unlimited.
tur	String	The unique ID assigned to identify a card.

Event exception monitor

monitorId = EVENT_EXCEPTION

This monitor reports the following data when an event exception is detected.

Field	Type	Description
err_msg	String	The descriptive error message associated with this exception.
ext1	String	Additional information associated with this exception.
ext2	String	Additional information associated with this exception.

Initialization exception monitor

monitorId = EVENT_LAST_CRASH

This monitor reports the following data when an initialization related exception is detected.

Field	Type	Description
next_step_type	String	The action required after the last crash is detected.

White box initialization exception monitor

monitorId = EVENT_WB_EXCEPTION

This monitor reports the following data when a white box initialization exception is detected.

Field

Type

Description

err_msg

String

The error message returned upon detection of a white box initialization exception.

is_success

String

Indicates whether the initialization is successful.

Valid values are:

true: Successful
false: Failed

Event listener monitor

monitorId = EVENT_ACTION

This monitor reports the following data when the scenarios defined in the Events occur.

Field	Type	Description
current_id	String	The unique ID to identify the current SDK.
behavior	String	The action currently being performed by the SDK in this scenario.
ext	String	Additional information associated with this scenario.
msg	String	The message returned in this scenario.

Events

Scenario	*behavior*	*ext*	*msg*
The connect API is called and the internal modules are initialized and ready to use.	Connected	N/A	SDK is already connected
The destroy API is called and the SDK instance is disposed.	Destroy	N/A	SDK is already destroy
The isPaymentAvailable API is called but the token is not connected.	isPaymentAvailable	"currentStatus = " + `TokenStatus.TOKEN_NOT_CONNECTED`	TokenStatus.TOKEN_NOT_CONNECTED
The isPaymentAvailable API is called but the token is in progress.	isPaymentAvailable	"currentStatus = " + `TokenStatus.TOKEN_STATUS_IN_PROGRESS`	TokenStatus.TOKEN_STATUS_IN_PROGRESS
Calling isPaymentAvailable API is successful.	isPaymentAvailable	"currentStatus = " + `tokenStatus`	Query Token Status
The activatePayment API is called but the SDK is not connected.	activatePayment	`NFCActivateParams`	sdk is not connected
The activatePayment API is called but request parameters got issues.	activatePayment	"NFCActivateParams" + "config :" + `config.isNeedConfirmActivate()`	INPUT_PARAMS got issues
The activatePayment API is called but the device fingerprint service is null.	activatePayment	`NFCActivateParams`	Device FingerPrint Service is null
The activatePayment API is called but the device fingerPrint is empty or its length is less than 64-digit.	activatePayment	`deviceFingerPrint`	Device FingerPrint is empty or not exceed 64
Receive a push notification.	onNotificationDataReceived	`notificationData`	Receive Push Notification Data
Deactivate a transaction.	transactionDeactivate	N/A	processApdu transaction deactivate from terminal
Delete a card by server.	delete card	"tur=" + `tur`	Raised when the token status synced from the server reports the card as deactivated.
Delete a card by push.	delete card	"tur=" + `tur` + ",pushTokenStatus=" + `pushTokenStatus`	Raised when the token status received by push reports the card as deactivated.
Sync token status by push.	syncTokenStatusByPush	"tur=" + `tur` + ",pushTokenStatus=" + `pushTokenStatus`	Raised when a push notification triggers a token status sync.
Initiate the SDK.	sdk init	N/A	Raised when the SDK is initiated.
Reset the SDK.	sdk reset	N/A	Raised when the SDK is reset.
Clear the SDK.	sdk clear	N/A	Raised when the SDK is cleared.
Set a default card.	device save card	`"uid=$uid,cardId=$cardId"`	Raised when a default card is set for the user.
Check the local card status.	Check local card	`"device has card = $hasCard"`	Raised when the SDK checks whether the device already has a card.
Clear the `StorageServiceImpl`.	SharedPreferences clear	N/A	Raised when the stored key-value data is cleared.
Clear the `SharedPreferences`.	SharedPreferences clear	N/A	Raised when the SharedPreferences data is cleared.
Reset the `SharedPreferences`.	SharedPreferences clear	N/A	Raised when the SharedPreferences data is reset.

Database storage initiation monitor

Note: This monitor supports SDK version 1.5 or later.

monitorId = EVENT_DB_STORAGE_INIT

This monitor reports data when the SDK finishes initializing its encrypted card database during the connection process. It captures how long the initialization took, whether a data migration was performed, and the overall result. This event signals that card storage is ready for use.

Field	Type	Description
current_id	String	The unique ID to identify the current user.
init_time	String	The total time, in milliseconds, taken to initialize the database.
is_migration	String	Indicates whether a data migration was performed during initialization. Valid values are: `true`: A data migration was performed. `false`: No data migration was performed.
migration_ret	String	The result of the data migration. Valid values are: `true`: Successful `false`: Failed
ret	String	The result of the database initialization. Valid values are: `true`: Successful `false`: Failed

Database storage exception monitor

Note: This monitor supports SDK version 1.5 or later.

monitorId = EVENT_DB_STORAGE_EXCEPTION

This monitor reports data when a database operation in the card storage layer fails or encounters an error. Typical scenarios include a failed write, an incomplete data migration, or a schema upgrade failure. This event indicates a persistence issue that may leave card data temporarily unavailable.

Field	Type	Description
current_id	String	The unique ID to identify the current user.
err_msg	String	The error message describing the exception.

Transaction result monitor

Note: This monitor supports SDK version 1.5 or later.

monitorId = EVENT_NEW_TRANSACTION

This monitor reports data when a contactless (tap-to-pay) transaction completes, regardless of whether it succeeds or fails. It captures the transaction result, processing time, transaction type, and error details on failure, providing visibility into each tap-to-pay attempt.

Field	Type	Description
ret	String	The result of the transaction. Valid values are: `true`: Successful `false`: Failed
transaction_time	String	The total time, in milliseconds, taken to process the transaction.
command_i	String	The time taken to execute the command with sequence number `i`. In a standard MCBP interaction, `i` ranges from 0 to 8.
errorCode	String	The error code associated with the transaction failure.
command_sum	String	The total time, in milliseconds, spent executing all commands within the transaction.
apdu_node	String	The name of the last APDU command received.
cApdu	String	The content of the last APDU command received.
rApdu	String	The content of the last APDU response sent.
current_id	String	The unique ID to identify the current user.
tur	String	The unique ID assigned to identify a card.
mcc	String	The merchant category code (MCC).
type	String	The type of the transaction. Valid values are: `PURCHASE`: Ordinary transaction `REFUND`: Refund `CASH`: Cash withdrawal `TRANSIT`: Transportation transaction `PURCHASE_WITH_CASHBACK`: Purchase with cashback `UNKNOWN`: Unknown type
amount	String	The transaction amount.
merchant_name	String	The name of the merchant. The value is hex-encoded.
country_code	String	The country code. The value is hex-encoded.
isDebitBin	String	Indicates whether the card is a debit card. Valid values are: `true`: The card is a debit card. `false`: The card is not a debit card. Note: In the Alipay+ environment, this field always returns `false`.
customIAD	String	The customized issuer application data.
transit_check_advancepay_limit_switch	String	Indicates whether the advance pay limit check is enabled for transit transactions. Valid values are: `0`: Disabled `1`: Enabled
transit_advancepay_limit_status	String	The advance pay limit status returned by the server. Valid values are: `0`: The payment amount is limited. `1`: The payment amount is unlimited.
connect_time	String	The total time, in milliseconds, taken for SDK initialization.
connect_timestamp	String	The timestamp at which SDK initialization completed.
transaction_info_json	String	The full transaction information in JSON format.

Silent replenish API monitor

Note: This monitor supports SDK version 1.5.1 or later.

monitorId = EVENT_REPLENISH_SILENCE

This monitor reports data when the silent replenishment process is triggered in the background, typically when the token is ready to tap but credentials are running low.

Field	Type	Description
replenishResult	String	The result of the replenishment process. Valid values are: `0`: Failed `1`: Successful
errorCode	String	The error code returned by the silent replenishment callback. Empty when the replenishment succeeds.
errorMsg	String	The error message returned by the silent replenishment callback. Empty when the replenishment succeeds.
tur	String	The unique ID assigned to identify the card being replenished. Omitted when empty.

Credential invalid monitor

Note: This monitor supports SDK version 1.9.0 or later.

monitorId = EVENT_CREDENTIAL_INVALID

This monitor reports data when a transaction credential is detected as invalid during a contactless transaction.

Field	Type	Description
current_id	String	The card identifier (`cardId`) of the credential that failed validation. Falls back to the literal string `"uid is empty"` when the cardId is `null` or blank.
atc	String	The Application Transaction Counter (ATC) of the invalid credential, as a decimal string.
credentials_invalid_reason	String	Why the credential was rejected. Valid values are: `MD_MISSING`: The MD (Mobile Data / SessionKey MD) is `null` or zero-length. `UMD_MISSING`: The UMD (Mobile Data / SessionKey UMD) is `null` or zero-length. `BOTH_MISSING`: Both MD and UMD are `null` or zero-length. `UNKNOWN`: Neither MD nor UMD is missing but the credential was still rejected. `unknown`: Fallback value returned by the client-side tracker when the reason received from the server is `null` or does not match any of the four values listed above (`MD_MISSING`, `UMD_MISSING`, `BOTH_MISSING`, and `UNKNOWN`).
tur	String	The unique token reference assigned to identify the card. Omitted when empty.

Database verification success monitor

Note: This monitor supports SDK version 1.10.0 or later.

monitorId = EVENT_DB_VERIFY_SUCCESS

This monitor reports data when the database verification passes all four checks. It is the positive counterpart of EVENT_DB_VERIFY_FAILED.

Field	Type	Description
current_id	String	The unique ID to identify the current user. Returns the literal string `"uid is empty"` when the user ID is unavailable.

Database verification failure monitor

Note: This monitor supports SDK version 1.10.0 or later.

monitorId = EVENT_DB_VERIFY_FAILED

This monitor reports data when one or more of the four database verification checks fail. When this event is emitted, the SDK has already wiped the local card database. This event is the earliest signal that the local card database was wiped.

Field	Type	Description
current_id	String	The unique ID to identify the current user. Returns the literal string `"uid is empty"` when the user ID is unavailable.
userListVerify	String	Indicates whether the `user_list` table checksum verification passed. Valid values are: `true`: Successful `false`: Failed
mcCardListVerify	String	Indicates whether the `mc_card_list` table checksum verification passed. Valid values are: `true`: Successful `false`: Failed
userCardListVerify	String	Indicates whether the `user_card_list` table checksum verification passed. Valid values are: `true`: Successful `false`: Failed
nfcCardVerify	String	Indicates whether the NFC card data held by the SDK matches the persisted card record for this user. Valid values are: `true`: Matched `false`: Mismatched or missing

Database migration monitor

Note: This monitor supports SDK version 1.9.5 or later.

monitorId = EVENT_DB_MIGRATE

This monitor reports data when the database migration runs. Currently, only migrations from version 1 are instrumented. The event fires exactly once per migration attempt and reports one of two results:

Checksum pre-verification passed: Reports the actual migratedCount and failedUpdateCount.
Checksum pre-verification failed: Reports checksumValid as false and zero for both counters. No rows are migrated.

Field	Type	Description
current_id	String	The unique ID to identify the current user. Returns the literal string `"uid is empty"` when the user ID is unavailable.
oldVersion	String	The database version being migrated from.
newVersion	String	The target database version.
checksumValid	String	Indicates whether the pre-migration checksum verification passed. When `false`, no rows are migrated and both counters below are `0`. Valid values are: `true`: Successful `false`: Failed
migratedCount	String	Number of rows whose checksum was successfully recomputed and written back during the migration loop.
failedUpdateCount	String	The number of rows that failed to update during the migration. For silent write failure, see `EVENT_DB_WRITE_RESULT`.

Database write result monitor

Note: This monitor supports SDK version 1.10.0 or later.

monitorId = EVENT_DB_WRITE_RESULT

This monitor reports data when a database write operation completes, including both successful writes and silent failures.

Field	Type	Description
current_id	String	The unique ID to identify the current user. Returns the literal string `"uid is empty"` when the user ID is unavailable.
operation	String	The type of write. Valid values are: `insert` `insertOrUpdate` `update` `delete`
table	String	The target table (or table group). Valid values are: `user_list` `mc_card_list` `user_card_list` `watch_devices` `all_tables`
is_success	String	Indicates whether the write succeeded. Valid values are: `true`: Successful `false`: Failed
context	String	The operation context that triggers the write. Valid values are: `migrationData` `initUser` `saveMCCard` `wipeCardData` `wipeAllData`

Payment activation result monitor

Note: This monitor supports SDK version 1.10.0 or later.

monitorId = EVENT_ACTIVATE_PAYMENT_RESULT

This monitor reports data at each exit point of the activatePayment flow, covering both early-rejection checks and the final outcome. It fires once per activatePayment invocation.

Field	Type	Description
current_id	String	The unique ID to identify the current user. Returns the literal string `"uid is empty"` when the user ID is unavailable.
phase	String	The phase of activatePayment where the result was produced. Valid values are: `gate_check`: An early-return check rejected the call before processing. Possible reasons include: SDK not connected, invalid input parameters, or an invalid device fingerprint. durationMs is `0` for all `gate_check` events. `issue_card`: The card issuance step completed. `replenish`: The post-issue replenish step completed.
is_success	String	Indicates whether the phase completed successfully. Valid values are: `true`: Successful `false`: Failed
durationMs	String	Elapsed time in milliseconds from when activatePayment was invoked to when this event was emitted.
errorCode	String	The error code associated with the failure. Only present when non-empty. For example: `NOT_CONNECT` and `INPUT_PARAMS`.
errorMsg	String	The error message associated with the failure. Only emitted when non-empty.

Blacklist configuration source monitor

Note: This monitor supports SDK version 1.10.0 or later.

monitorId = EVENT_BLACKLIST_CONFIG_SOURCE

This monitor reports data at the start of each transaction, recording which configuration source contributed to the effective transaction blacklist. It is emitted once per transaction.

Field	Type	Description
config_source	String	Which sources contributed to the effective blacklist. Valid values are: `LOCAL_ONLY`: Only the local built-in configuration was used. This occurs when no remote configuration is available, or when the local configuration is explicitly enabled and no remote entries exist. `REMOTE_ONLY`: Only the remote configuration was used. `MERGED`: Both remote and local entries were union-merged.
use_local_config	String	Indicates whether the local built-in configuration is included in the effective blacklist. Defaults to `true` when no remote configuration is available. Valid values are: `true`: Local safety net is merged in. `false`: Local safety net is bypassed.
country_code	String	The terminal country code extracted from PDOL (EMV tag `9F1A`). The value is hex-encoded. Empty when the terminal did not provide this value.
current_id	String	The unique ID to identify the current user.
tur	String	The unique ID assigned to identify the card.

Response parameters

N/A

Sample

The following is a sample about how to use this SPI:

copy
public class DemoNFCMonitor implements NFCMonitor {
    @Override
    public void track(String monitorId, Map<String, String> params) {
        params.put("monitor_type", monitorId);
        Log.d("NFC_MONITOR", JSON.toJSONString(params));
    }
}

The following is a sample of the returned params parameter:

copy
{"countCredential":"24","errorCode":"","errorMsg":"","monitor_type":"EVENT_REPLENISH","replenishResult":"true"}  

Note: track(String monitorId, Map<String, String> params) receives the event VALUE, not the constant name. Match on the value. One constant and value diverge: EVENT_ID_INIT_EXCEPTION carries the value EVENT_LAST_CRASH, not EVENT_INIT_EXCEPTION.