Environment configurations

This document introduces the SDK environment configurations for different phases or scenarios.

Card activation phase

The following table lists the configurations used during the card activation phase.

Key	Configuration	Supported SDK version	Data type	Description
nfc_issue_config	applyTokenTimes	1.0.0	Number	The number of polls for the token application. Default value: `0`
	applyTokenInterval	1.0.0	Number	The polling interval for the token application. The unit is milliseconds (ms). Default value: `25`
	activateTimes	1.0.0	Number	The number of polls for the activation. Default value: `0`
	activateInterval	1.0.0	Number	The polling interval for the activation. The unit is milliseconds (ms). Default value: `25`
	sessionTimes	1.0.0	Number	The number of polls for the session. Default value: `0`
	sessionInterval	1.0.0	Number	The polling interval for the session. The unit is milliseconds (ms). Default value: `25`

Sample

copy
{
  "nfc_issue_config": {
    "applyTokenTimes": 10,
    "applyTokenInterval": 2000,
    "activateTimes": 10,
    "activateInterval": 2000,
    "sessionTimes": 10,
    "sessionInterval": 500
  }
}

Transaction phase

The following table lists the configurations used during the transaction phase.

Key	Configuration	Supported SDK version	Data type	Description
nfc_transaction_config	isSupportTransit	1.0.0	Boolean	Whether to support transportation scenarios. Valid values are: `true`: supported `false`: not supported Default value: `false` This remote configuration takes precedence over isSupportTransit passed via the init API.
	isSupportTransitWithoutConsent	1.1.12	Boolean	Whether the traffic payment is supported while the screen is locked. Valid values are: `true`: supported `false`: not supported Default value: `false` This remote configuration takes precedence over isSupportLockScreenPay passed via the init API.
	asyncAmountLimitSwitch	1.2.0	Boolean	Whether to allow querying the password-free payment amount when the isPaymentAvailable API is called. Valid values are: `true`: allowed `false`: not allowed Default value: `false` This remote configuration takes precedence over asyncAmountLimitSwitch passed via the init API.
	canQueryAmountLimit	1.2.0	Boolean	Whether to query and use the password-free amount from the remote configuration. Valid values are: `true`: Query and use. `false`: Do not query and use. Default value: `false` Note: The required interface is not yet fully supported. However, configuring this will not block sandbox testing environments.
	requireDeviceUnlock	1.2.11	Boolean	Whether the device must be unlocked to use NFC functionality. Valid values are: `true`: required `false`: not required Default value: `false`
	allowTapTransaction	1.2.11	Boolean	Whether the NFC functionality is enabled. Valid values are: `true`: enabled `false`: disabled Default value: `true`
	isSupportCardStatusJudgement	1.2.19	Boolean	Whether to support card status judgment in advance. Valid values are: `true`: supported `false`: not supported Default value: `false`
	failedCallbackInterval	1.2.18	Int	The interval between the reports of the same error code. The unit is milliseconds (ms). Default value: `500`
	isWalletActionRequired	1.2.18	Boolean	Whether the refund process requires a second confirmation. Valid values are: `true`: required `false`: not required Default value: `false`
	isSupportCardProfileRepair	1.2.19	Boolean	Whether to support card token re-activation if a card content parsing error occurs. Valid values are: `true`: supported `false`: not supported Default value: `true`
	isCheckTransitAdvancePayLimit	1.4.5	Boolean	Whether to check the payment amount limit of the transit card. Valid values are: `true`: Check the payment amount limit. If the limit is reached, the tap fails. `false`: Do not check the payment amount limit. The tap succeeds regardless of the payment amount limit Default value: `false`
	isSwitchDBStorage	1.5.0	Boolean	Whether to switch to DB storage. Valid values are: `true`: switch `false`: do not switch Default value: `false`
	isSwitchInitCard	1.5.0	Boolean	Whether to switch to a new initialization card token information in the tap process. Valid values are: `true`: switch `false`: do not switch Default value: `false`
	isEventTransactionTrackingV2	1.5.0	Boolean	Whether to switch to the SDK version 1.5 parameters of the NFCMonitor API. Valid values are: `true`: switch `false`: do not switch Default value: `false`
	sameTapJudgementLevel	1.5.0	Int	The time interval between two taps that will be considered as the same tap. The unit is milliseconds (ms). Default value: `0`
	timeOfDelayReport	1.5.0	Int	The time delay to report failure results after a business failure. The unit is milliseconds (ms). Default value: `0`
	isSupportNewTransactionResultReport	1.5.0	Boolean	Whether to support the new transaction result report mechanism. Valid values are: `true`: supported `false`: not supported Default value: `false`

Sample

copy
{
  "nfc_transaction_config":{
    "isSupportTransit":true,
    "isSupportTransitWithoutConsent":true,
    "asyncAmountLimitSwitch":false,
    "canQueryAmountLimit":false,
    "requireDeviceUnlock":false,
    "allowTapTransaction":true
  }
}

Transit

The following table lists configurations specifically for transit scenarios.

Key	Configuration	Supported SDK version	Data type	Description
nfc_transit_config	terminalCountryCode	1.1.16	String	The country code of the transaction.
	merchantCategoryCode	1.1.16	String	The merchant category code (MCC) that represents the categorization of the merchant's business type.
	currencyAmount	1.1.16	Number	The transaction amount.
	merchantNameAndLocation	1.1.16	String	The merchant's name, address, and location.

Sample

copy
{
  "nfc_transit_config": [
    {
      "terminalCountryCode": "0458",
      "merchantCategoryCode": "4131"
    },
    {
      "terminalCountryCode": "0458",
      "merchantCategoryCode": "4111"
    },
    {
      "terminalCountryCode": "0458",
      "merchantCategoryCode": "4784"
    },
    {
      "terminalCountryCode": "0458",
      "merchantCategoryCode": "1234"
    },
    {
      "terminalCountryCode": "0458",
      "merchantCategoryCode": "0000"
    }
  ]
}

Initialization

The following table lists the configurations used during the initialization phase.

Key	Configuration	Supported SDK version	Data type	Description
nfc_init_config	init_monitor	1.1.25	Boolean	Whether to activate initialization monitoring. If it is set to `true`, an initialization flag is recorded and the monitor initialization logic is determined based on this flag. Default value: `true`
	next_step_type	1.1.25	Number	The next step to do upon detecting a previous crash. Valid values are: `1`: Upon detecting a previous crash, skip the remaining initialization steps and returns false directly `0`: Upon detecting a previous crash, continue with the remaining initialization steps. Default value: `0`
	invalidate_time_stamp	1.1.25	Number	The validity period for the recorded initialization flag. The unit of this value is seconds (s). Default value: `604800` (equivalent to 7 days)

Sample

copy
{
  "nfc_init_config": {
    "init_monitor": true,
    "next_step_type": 1,
    "invalidate_time_stamp": 604800
  }
}

Transaction blacklist

The following table lists configurations for the transaction blacklist.

KEY	Configuration	Supported SDK version	Data type	Description
nfc_transaction_black	countrycode values	1.1.27	List<String>	The transaction types that are blacklisted. For the valid transaction types, see Transaction types.

Transaction types

The following table lists the transaction types and their corresponding richTransactionType.

Value	Corresponding richTransactionType	Description
`ALL`	N/A	All transaction types
`PURCHASE`	`PURCHASE`	Ordinary transactions
`REFUND`	`REFUND`	Refund
`CASH`	`CASH`	Cash withdrawal
`TRANSIT`	`TRANSIT`	Transit transactions
`CASHBACK`	`PURCHASE_WITH_CASHBACK`	Purchases with cashback

Sample

copy
{
  "nfc_transaction_black": {
    "0344": [
      "TRANSIT"
    ],
    "0156": [
      "ALL"
    ]
  }
}

Transaction whitelist

The following table lists the configurations about the transaction whitelist.

Key	Configuration	Supported SDK version	Data type	Description
nfc_transaction_black	terminalCountryCode	1.4.3	String	The country code of the transaction.
	transactionType	1.4.3	String	Transaction types. Valid values are: `PURCHASE`: Ordinary transactions `REFUND`: Refund `CASH`: Cash withdrawal `TRANSIT`: Transit transactions `PURCHASE_WITH_CASHBACK`: Purchases with cashback
	needDebitBin	1.4.3	Boolean	Whether debit card bins are required.

Sample

copy
{
  "nfc_transaction_black": {
    "terminalCountryCode": "0344",
    "transactionType": "TRANSIT",
    "needDebitBin": true
  }
}

Manage configurations with blacklist and whitelist

The following table lists configurations for managing nfc_transaction_config items using blacklists and whitelists.

Note: Only the allowTapTransaction configuration is supported.

key	item	Supported SDK version	Data type	Description
nfc_payment_access_control_config	key	1.2.18	String	The configuration that needs to be managed according to the blacklist and whitelist. Valid value is`allowTapTransaction` which indicates whether to allow tapping to pay.
	blackList	1.2.18	List<String>	A list of user IDs, who are blacklisted and the configuration for them is set to `false` for the configuration specified in the key parameter.
	whiteList	1.2.18	List<String>	A list of user IDs, who are whitelisted and the configuration for them is set to `true` for the configuration specified in the key parameter.

Sample

copy
{
  "nfc_payment_access_control_config": [
    {
      "key": "allowTapTransaction",
      "blackList": ["123", "456", "789"], // Users that are not allowed to make tap payment
      "whiteList": ["123", "456"] // Users that are allowed to make tap payment
    },
    // other configurations
    ...
  ]
}