Troubleshooting During Testing and Production

The errors listed below typically occur during the Proof of Concept (POC) process, the initial integration attempts, or the deployment of the SDK in staging and production environments.

For each transaction process stage, we will present the most common errors, along with a structured troubleshooting path and the necessary checks for each situation.

This systematic approach facilitates the identification and resolution of issues, ensuring a smoother transition between the development, staging, and production phases.

How to Activate the Terminal

Terminal activation, as discussed in previous sections, is a critical step that requires compliance with specific prerequisites in the production environment of the Android operating system.

During the terminal creation process, if these prerequisites are not met, the SDK will return an error from the TerminalInitializingErrorViewData class, with the description DEVICE_STATE_FAILED, indicating that the activation was unsuccessful.

Below, we outline the main reasons that may cause this failure.

1. Required Permissions to Operate the SDK within the Application

Initially, it is necessary to verify if the application has access to the following Android permissions:

To verify if the permissions have been requested, open the AndroidManifest.xml file, which should be accessed by the Android project developer.

In this file, some permissions are automatically configured, while others need to be explicitly declared according to Android's security policy.

Additionally, you can request a screenshot from the developer to confirm the permissions directly on the device.

Even if the permissions are implemented in the application, in the production environment (when the app is downloaded from the store), Android will request user confirmation to access certain features, such as the camera or microphone.

It is essential to verify whether the application has made these requests and if the user has granted permission for these features.

If there are any doubts regarding permission grants, recommend reinstalling the application. This will allow the necessary steps to be repeated, ensuring that permissions, such as microphone and NFC, are requested and granted at the appropriate time.

1. Root Mode

If the superuser is logged in and enabled on Android, the SDK will not be able to complete the terminal creation phase, either in staging or production.

To check if the device is in root mode, follow a process similar to the one described in Section 2 for log collection:

1. Ask the application developer to configure the build variants in Android Studio for the staging environment (hml) while using the staging SDK.

2. With the project open in Android Studio, access the console window by pressing Alt + F12.

   • If the developer is unfamiliar with build variants, recommend reading Section 4: Environment Preparation to Get Started.

3. Connect the mobile device to the computer using a USB cable and enter the following command:

adb shell

Next, check if it is possible to access the Android superuser on the mobile device:

su

If the device requests permission or switches to superuser (root) mode, it indicates that root access is enabled.

On the other hand, if the command returns a message like "command not found", the device does not have root access.

1. Developer Mode

Developer mode is allowed only for the staging SDK, but not for the production SDK.

If you are in production and encounter the DEVICE_STATE_FAILURE error during the terminal creation step, you must disable developer mode on the Android device where the application is installed.

To disable developer mode, follow these steps:

1. Open the Settings menu on Android and look for Developer Options or Programmer Options, depending on the device model and Android version.

2. If this submenu is not found, it means that developer mode has never been enabled.

To confirm if developer mode is active:

1. Go to the About Phone submenu in the Settings menu.

2. Tap seven times on the Build Number field. After this, Android will display a message confirming that Developer Options have been enabled.

3. Open the newly created Developer Options menu and disable developer mode.

This action will ensure that the device is properly configured for the production environment.

1. Potentially Malicious Applications

Another reason for the DEVICE_STATE_FAILURE error during the terminal creation phase is the presence of applications that can monitor data exchange between apps, enable root mode, or collect sensitive data, compromising the security of payment data read via NFC.

This verification takes place in both staging and production modes.

Below is a list of known applications that may cause this error (not limited to these, as variations with similar effects may exist):

• Magisk

• Frida

• Cydia Substrate

• SuperSU

• Xposed

If any of these applications are found on the device, we strongly recommend performing a factory reset.

This ensures that tests are restarted in a clean environment, preventing potential residual interference with the integrity of the operating system, even after these applications have been removed.

1. Apps Installed Outside the Store

In the production environment, applications installed outside the official store may be flagged by Play Integrity, marking the device as unsafe for transactions.

If there is suspicion of such apps, uninstall them and attempt to create the terminal again.

The SDK continuously performs security checks to ensure that the device is always classified as safe, maintaining the integrity and security of transactions.

Other less complex issues returned by the TerminalInitializingErrorViewData view during the initialization phase may include:

How to Activate the Session

After successfully completing the terminal integrity verification process, the next step is session creation.

At this stage, the application is validated based on its credentials and certificates in Google Play. If no issues are detected, the SDK will proceed to the card request process.

The most common issues in this phase generally fall into two categories:

1. Failure in Retrieving Application Data from the Store:

   • The developer must ensure that all required information is available and up to date.

2. Version Update Without Communication:

   • When a new version of the application is published in the store, the developer must officially request the release of this version in production with First Tech.

   • This process ensures authorized SDK usage control on customer devices

To release the version, a support ticket must be opened with the following three essential details:

• SHA-256 certificate fingerprint

• Package Name

• Version Code

SHA-256 - Application Signing Certificate Fingerprint

The SHA-256 is a unique fingerprint generated by the application signing certificate in Google Play. It is public and used to authenticate the application, ensuring its exclusivity.

First Tech requires this data only the first time the application is distributed in the store.

The SHA-256 generation process is managed by Google and involves several steps, which can be found in the official documentation.

To provide the required value, follow these steps:

• Access the Google Play Console settings menu (more details here).

• Navigate to Setup > App Integrity > App Signing Key Certificate > SHA-256 Certificate Fingerprint.

• Copy the displayed hexadecimal value and send it to First Tech.

This step is essential to validate the integration and allow the authorized use of the SDK.

Exemplo de SHA-256 certificate Fingerprint

BD : 92 : 64 : B0 : 1A : B9 : 08 : 08 : FC : FE : 7F : 94 : B2

Package Name - Unique Identification Name of the Android Application

The Package Name is the unique identifier for an Android application, used to differentiate it from other apps installed on the device. This naming convention prevents conflicts between applications and is essential for both system functionality and software testing, whether manual or automated.

Although the Package Name is automatically assigned when the app is submitted to Android, it can be changed if necessary. The format typically follows the pattern: com.yourdomain.appname.

For example, if the developer's website is meusite.com and the app is called MeuApp, the Package Name could be com.meusite.meuapp.

How to locate the Package Name:

Ask the developer to access the build.gradle file of the app module. Inside the defaultConfig object, locate the applicationId variable, which will contain the Package Name. This value will be unique for each supported app.

This information is essential for the correct integration with the SDK and for accurately identifying the app in the store and on devices.

Version Codes - Application Version Identification

The Version Code represents the version of the application and is used by First Tech to identify which product versions are valid for the Tap to Phone SDK during the session creation phase. This parameter is cumulative, meaning all valid versions must be sent, allowing multiple versions to be active simultaneously.

Important Notes about Version Code:

• The list of valid versions must include all corresponding strings, as only the latest version provided will be considered as the reference.

• Clients can submit future versions, allowing app updates to be performed without the need to immediately open new support tickets.

• It is a good practice to notify First Tech when older versions are no longer valid. This prevents transactions on those versions and forces end users to update the app, ensuring greater security and compatibility.

How to Identify the Version Code:

Follow the same procedure used to locate the Package Name, but look for the versionCode variable inside the defaultConfig object in the build.gradle file of the app module.

Ensuring the correct submission of this information is essential for secure and efficient operation.

Example of Sending Data by Email to Enable Version in Production

Dear First Tech Team, good morning!

Could you please enable our app in production? Here are the details:

SHA-256 of the app on the store: BD : 92 : 64 : B0 : 1A : B9 : 08 : 08 : FC : FE : 7F : 94 : B2 Package Name of the app: com.notke.paymentapp Version Codes: 20, 21, 22, 23, 24, and 25

For Tap to Phone SDK versions above 1.0.20, the application registration process in production will return to the developer three fields that should be used exclusively in the production environment. These fields should be added in the SDK call within the StartPayment method. The variables are:

Client Id
Cliente Secret
Scope

These variables must be included in the call along with the CPF, CNPJ, Customer ID, and other information that the SDK already requests from customers. They are essential to complete the session creation process and allow progression to the following steps. Additional details about these variables can be found in the technical specifications intended for the developer.

If this step is not performed correctly, the TerminalSessionCreatedErrorViewData view will display the DEVICE_STATE_FAILURE error, which is the most common issue encountered during the session activation phase.

Other minor and rarer issues may also occur during the session activation process. Below, we list these issues along with their possible solutions:

Bringing the Card Close and Starting the Transaction

If the terminal and session are successfully activated, the device will be ready to perform the card proximity. To avoid issues, it is recommended to refer to Section 7: Troubleshooting During Testing and Production for best practices on handling the device, ensuring that the application does not experience read timeouts caused by improper card positioning or difficulties with the NFC reader within the time allowed for the operation.

Additionally, other important factors include:

• Stable network: Ensure that the connection is reliable to prevent interruptions.

• Valid card: Use an active card, not expired, with available balance or limit, and with the proximity payment function activated.

• Correct card mode: Some neobanks have inverted debit and credit functions. For example, using a debit card as credit may result in the error "No application selector for the card".

Another point of attention is during the programming phase. Ensure that the PaymentType enums are correctly configured, as reversed values can lead to similar failures.

A rarer, but possible situation is the difficulty in reading newer or less common cards due to the absence of Application IDs in the SDK database. This problem may also generate the error "No application selector for the card." In this case, it will be necessary to open a ticket so that First Tech, in collaboration with the acquirer, can review the tables responsible for recognizing the card and implement the necessary updates. The SDK will be automatically updated, with no action required from the developer, on the next transaction attempt.

At this point, the errors displayed in the TerminalPaymentErrorViewData view may have two distinct origins:

• Errors related to the SDK.

• Errors related to authorization.

Here are the common errors related to the SDK and their possible solutions:

The transaction can also be denied due to authorization failures with the acquirer. This is related to card failures, fraud prevention rules, password issues, and the availability of the payment ecosystem: authorization services from card networks, acquirer availability, and others. The returned errors are aligned with ABECS Normative 21, which can be found here for issues with the acquirer.

It is important that these returns are displayed to customers, mimicking the behavior of a common POS, and providing visibility into errors that may or may not be retried. This helps protect the merchant from being charged fees for misuse of authorization attempts by the acquirer through the card networks (Visa, Mastercard, and Elo).

To verify these errors, in addition to the response in the TerminalPaymentSuccessViewData and TerminalPaymentErrorViewData views, respectively for transaction approvals and denials, the meta field will return an object with the details of this transaction from the acquirer side, indicating the authorization processing.

Example of the Meta Field Filled if the Transaction is Denied

{
   "providerResponse": {
      "mti": "2210",
      "processingCode": "002000",
      "amount": "9862000000000041",
      "transmitionDateTime": "20250123133118",
      "stan": "842379",
      "transactionDateTime": "20250123133117",
      "authorizerId": "16",
      "muxipayResponseCode": "8001",
      "authorizerResponseCode": "05",
      "terminalId": "00000007",
      "merchantId": "00595154000173",
      "emvTags": "8a023035",
      "customerId": "FIRSTTECH",
      "displayCustomerMessage": "TRANSACAO NEGADA\nCONTATE A\nCENTRAL DO SEU\nCARTAO",
      "trackingNumber": "020001419451",
      "muxipayUniversalId": "00ad54c01b8d064501e1ec6b34df8eac",
      "initializationRequired": "10",
      "hostStan": "000725",
      "error": {
         "code": "invalid operation",
         "message": "Error occurred on authorize message",
         "metadata": {
            "acquirer": "rejected",
            "authorizer": "do_not_honour"
         }
      }
   },
   "error": {
      "type": "acquirer",
      "code": "invalid operation",
      "message": "Error occurred on authorize message",
      "metadata": {
         "acquirer": "rejected",
         "authorizer": "do_not_honour"
      }
   },
   "status": "COMPLETED_WITH_ERROR",
   "reason": "OPERATION_ERROR"
}

Example of the Meta Field Filled if the Transaction is Authorized

{
   "mti": "2210",
   "muxipayUniversalId": "67bea6f89c319638f35e2b9273739df5",
   "receipt": {
      "merchant": {
         "message": "DOCK - Via Loja\n\nFIRST CUSTOMER\nCNPJ: 10179118609\nTID: 020001419130\n\n*** *** **** 5461\nMASTERCARD\nAID: A0000000041010\n23/01/25                         13:04\nCV: 855614\nValor: R$ 0,23\nForma de pagamento: Crédito\nÀ vista\nTerm: 00000486\n\nDADOS ORIGINAIS DA VENDA\nValor: R$ 0,23\nTerm: 00000486\nTransação autorizada pelo emissor\n"
      },
      "customer": {
         "message": "DOCK - Via Cliente\n\nFIRST CUSTOMER\nCNPJ: 10179118609\nTID: 020001419130\n\n*** *** **** 5461\nMASTERCARD\nAID: A0000000041010\n23/01/25                         13:04\nCV: 855614\nValor: R$ 0,23\nForma de pagamento: Crédito\nÀ vista\nTerm: 00000486\n\nDADOS ORIGINAIS DA VENDA\nValor: R$ 0,23\nTerm: 00000486\nTransação autorizada pelo emissor\n"
      }
   },
   "displayMessages": {
      "customer": "TRANSACAO APROVADA"
   },
   "providerResponse": {
      "mti": "2210",
      "processingCode": "003000",
      "amount": "9862000000000023",
      "transmitionDateTime": "20250123130431",
      "stan": "855614",
      "transactionDateTime": "20250123130429",
      "authorizerId": "16",
      "retrievalReferenceNumber": "020001419130",
      "authorizationCode": "043063",
      "muxipayResponseCode": "8000",
      "authorizerResponseCode": "00",
      "terminalId": "00000486",
      "merchantId": "10179118609",
      "emvTags": "8a023030",
      "customerId": "BIPPAGAMENTOS",
      "displayCustomerMessage": "TRANSACAO APROVADA",
      "trackingNumber": "020001419130",
      "muxipayUniversalId": "67bea6f89c319638f35e2b9273739df5",
      "initializationRequired": "10",
      "hostStan": "000012"
   },
   "status": "COMPLETED_SUCCESSFULLY",
   "reason": "COMPLETED_SUCCESSFULLY"
}