Tap On Phone via a Third-Party SDK App

This guide explains how to integrate Tap On Phone payment processing into a third-party Android app and what must be checked at each stage. It details the roles of support representatives and the merchant’s developers: the initial chapters explain the process and checks, while the technical appendix specifies the calls, fields, and app preparations.

The customer taps a credit card or digital wallet against an NFC-enabled mobile device. The app uses the SDK to perform the TAP operation and transfers the transaction data to the Cardcom API for processing in the system.

Key principle: both the transaction must be performed through the SDK and the request and response must be transferred to Cardcom using ProcessSDKTransaction. The result of both stages must be checked. A successful response from the SDK alone does not confirm that the transaction was received by the Cardcom system.

1. What is the role of each component?

Important: registerDevice and performTransaction are SDK operations within the Android app. PrepareDevice and ProcessSDKTransaction are API calls to Cardcom. They must not be confused.

2. What is required before starting?

For support representatives: device checks are initial checks. Library integration, SHA256 generation, APK preparation, and code changes are performed by the app developer.

3. Process sequence—what is performed and when?

Steps 1 and 2 prepare and register the device. They do not need to be repeated before every transaction while the registration remains valid. Steps 3 and 4 apply to each transaction separately.

If onRegisterNeeded is received, registration must be renewed: perform PrepareDevice again, followed by registerDevice, and save the new session data. The document does not define a policy for automatically retrying the transaction.

4. Preparing and registering the device

Device preparation — PrepareDevice

The app or integration component sends Cardcom the API details, terminal number, device identifier, manufacturer, and model. The response contains four key values:

Transfer the values received in the response for the relevant device and terminal. Do not enter an alternative value or assume that the multi-merchant terminal number is identical to the terminal number sent in the request.

Registering with the SDK — registerDevice

After receiving the preparation data, the developer calls registerDevice with TPN and MerchantCode. Successful PrepareDevice alone does not complete device registration in the SDK.

Registration key and validity

• session_key is the key supplied by the SDK after successful registration. Transfer it as sessionKey when performing a transaction.
• session_date is the key creation time, in milliseconds according to the document.
• session_expire_time is the expiration data, in milliseconds according to the document.

The document does not clarify whether session_expire_time is an absolute time or a validity duration. Do not infer an expiration formula from the name alone; the developer must verify how it is checked against the supplied SDK documentation. The document does not define a fixed registration period of a specific number of hours or days.

5. Performing a sale or refund

After successful registration and receipt of a valid session, the app calls performTransaction with two components: transaction data (inputObject) and the registration key (sessionKey). The SDK performs the TAP operation and returns a result to the app.

Sale versus refund: The document defines REFUND as a transaction type, but does not specify conditions for refunding an original transaction, refund limitations, or use of an original transaction number. Clarify the exact scenario before providing practical refund instructions.

Card details: Because the specification includes an option to return the full card number, transfer information for investigation only through the authorized channel, and conceal card details and secrets in examples and screenshots. There is no need to send support an API password or an exposed session key.

6. Setting up payments

Single-payment transaction

Pass NumberOfPayments = 1, CreditType = 1, and set both FirstPaymentSum and OtherPaymentsSum to 0. The total amount remains in the amount field.

Transaction with multiple payments

Calculate the first payment and the amount of each additional payment. For the division described in the document:

amount = FirstPaymentSum + (NumberOfPayments - 1) * OtherPaymentsSum

In the last example, 25 is charged for each of the two additional payments. The document does not define a rounding policy for agorot. When the division is not exact, verify the calculation method with the developer and responsible technical contact.

7. How is the transaction result read?

SDK response

The response may also include status, transaction_id, ApprovalNumber, UID, and ResultRecord. Save the complete response for transfer to Cardcom; do not construct an alternative response from a manually selected subset of fields.

Transferring the transaction to Cardcom — ProcessSDKTransaction

After receiving the SDK result, send Cardcom the original request and the received response, together with the identification details:

In the Cardcom response, check ResponseCode, Description, and DealNumber. The last is the transaction number in the Cardcom system. Do not confuse it with the transaction_id or UID received from the SDK.

Three different results:

• HTTP 200 is the status of the API call.
• response_code is a field in the SDK response.
• ResponseCode is a field in the Cardcom response.

Do not infer that the entire process succeeded by checking only one of them. The Cardcom success value 0 appears in the existing guide; the attached document presents the field as a number without a complete value table.

Support investigation recommendation — SDK succeeded, but there is no Cardcom receipt confirmation

Check whether ProcessSDKTransaction was sent, what its response was, and whether a DealNumber was received. If the response was lost or a timeout occurred, search for the transaction before requesting a new charge. The document does not describe an idempotency mechanism or an approved resubmission rule; technical investigation is required.

8. Retrieving transactions and devices for investigation

Retrieving transactions — GetTransactions

This call locates TAP transactions by terminal number and date range. The query range is limited to one year. This is a request-range limitation; the document does not establish the retention period for transaction history.

FromDate and ToDate are sent in ISO 8601 format, for example 2026-10-05T10:00:00. The document does not define the time zone, so when investigating a transaction, verify consistency between the device time, log time, and search time.

The response includes a Transactions list with details such as status, transaction number, date and time, transaction type, amount, number of payments, approval number, and external identifier. For investigation, compare several details together: terminal, time, amount, and transaction identifiers.

Retrieving devices — GetDevices

This call returns the TAP devices registered to the identified company. The request includes API details and a terminal number. The response includes a Devices list with UUID, manufacturer, model, TPN, MerchantCode, IsActive, creation date, and last activity date.

The appearance of a device in the list does not prove that its current session is still valid. Registration validity and SDK messages must be checked separately.

9. Initial checks and handling a support case

The following table is a suggested support-check sequence based on the integration stages. It is not an official error-code list or organizational escalation procedure.

Recommended information for technical investigation

• Relevant terminal and business numbers, device manufacturer and model, Android version, and app version.
• Device identifier DeviceUUID / UUID and the exact date and time of the incident, including the time zone.
• The stage at which the process failed: preparation, registration, SDK execution, or Cardcom processing.
• Callback or endpoint name, HTTP status, result code, and complete error message.
• Transaction type, amount, and payment data; available identifiers such as transaction_id, UID, ApprovalNumber, and DealNumber.
• Relevant requests and responses through an appropriate channel, after concealing passwords, session keys, full card details, and unnecessary personal information.

10. Examples for understanding the process

Example — regular transaction after successful registration

1. The device has already been prepared and registered, and the app holds a valid session.
2. To perform a ₪20 single-payment sale, the developer passes type = "SALE", amount = "20.00", CreditType = 1, NumberOfPayments = 1, and sets both payment amounts to 0.
3. The app calls performTransaction and receives the SDK response.
4. The app transfers the request and response to Cardcom using ProcessSDKTransaction.
5. The Cardcom processing result is checked and DealNumber is saved for locating the transaction.

Example — registration renewal is required

The SDK returns onRegisterNeeded. The developer restarts PrepareDevice and registerDevice and saves the new session. Registration renewal must be kept separate from determining whether the transaction may or should be performed again.

Example — SDK succeeded, but the Cardcom call timed out

Code "00" was received from the SDK, but there is no final response from ProcessSDKTransaction. This is an unverified result for the Cardcom receipt stage. Check logs and search for the transaction using the terminal, time, and amount. Escalate for technical investigation if the outcome cannot be determined; do not infer from the timeout that the charge was not performed.

11. Developer appendix—API calls and SDK data

All API calls detailed here are POST requests, include ApiName and ApiPassword, and are sent as application/json. Numbers, credentials, and device identifiers in the examples are illustrative and must be replaced with actual values.

Call URLs

PrepareDevice request

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "DeviceUUID": "DEVICE_UUID",
  "DeviceManufacturer": "DEVICE_MANUFACTURER",
  "DeviceModel": "DEVICE_MODEL"
}

The response includes ResponseCode, Description, TPN, MerchantCode, SapakMutavNumber, and RavMutavTerminalNumber.

Primary SDK operations

topService.registerDevice(tpn, merchantCode, registrationListener);
topService.performTransaction(inputObject, sessionKey, transactionListener);

These signatures are illustrative. Implement the listeners and result handling according to the supplied SDK package. Do not copy the callback examples as complete code: they do not include persistence, validity checks, error handling, or transfer to Cardcom.

performTransaction request—single ₪20 sale

{
  "type": "SALE",
  "amount": "20.00",
  "lang": "iw",
  "CustomObject": {
    "CustomerName": "",
    "CustomerEmail": "",
    "PhoneNumber": "",
    "HolderID": "",
    "NumberOfPayments": 1,
    "FirstPaymentSum": 0,
    "OtherPaymentsSum": 0,
    "CreditType": 1,
    "SapakMutavNumber": "VALUE_FROM_PREPARE_DEVICE",
    "TransactionUniqueIdForQuery": "",
    "AllowFullCardNumberInResponse": true
  }
}

The SapakMutavNumber value must come from the preparation response. Preserve field names and types exactly as specified, including capitalization.

ProcessSDKTransaction request—template only

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "RavMutavTerminalNumber": 654321,
  "DeviceUUID": "DEVICE_UUID",
  "SdkRequest": "THE_ORIGINAL_SDK_REQUEST",
  "SdkResponse": "THE_COMPLETE_SDK_RESPONSE"
}

In this example, SdkRequest and SdkResponse are placeholders only. Pass the actual SDK data. The document presents both fields as strings, but does not clearly specify the serialization format. Before implementation, verify in the API v11 schema whether a serialized JSON string or another structure is required. Do not send the placeholder text.

The SDK response also mentions transactionResult, customMessage, and DE48, alongside the other result fields. The document’s table does not clearly define the nesting hierarchy. Preserve the complete response and verify the structure against the SDK package; do not invent a flat JSON structure based on the table.

GetTransactions request

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "FromDate": "2026-10-01T00:00:00",
  "ToDate": "2026-10-05T23:59:59"
}

Record fields in Transactions

The response also includes ResponseCode and Description. Do not assume that the transaction status code is identical to the SDK code; the document does not include a complete value table for Status.

GetDevices request

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456
}

The response includes ResponseCode, Description, and a Devices list. Fields in each device are UUID, Manufacturer, Model, TPN, MerchantCode, IsActive, CreationDate, and LastActivityDate.

API errors

The document describes 400 Bad Request and 401 Unauthorized responses containing ResponseCode and Description. Check both fields together with the HTTP status; do not rely solely on the communication status.

12. Developer appendix—SDK installation and APK preparation

Permissions in AndroidManifest.xml

<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

The value android:required="false" in the manifest does not change the usage requirement: TAP requires a device with NFC. Declaring permissions in the file does not replace checking that the user actually granted the required permissions.

Libraries and project files

1. Create a libs folder in the project root if it does not exist.
2. Copy the supplied Cardcom-[version]-Release_Prod.aar into it.
3. In build.gradle, configure the topliteapp-PROD library and the AAR file. The file name and versions must match the actual integration package.
4. Configure the SDK repository according to the supplied package. The attached document specifies s3://denovo-android.s3.amazonaws.com/prod. Repository access details are provided separately through the authorized channel.
5. Use the supplied proguard-rules.pro file, or add its contents to the existing file.
6. After creating a new APK, perform Finalization according to the following steps.

The attached document lists version topliteapp-PROD:3.0.5.3. This is the version shown in the document and is not confirmation that it is current or suitable for every project. Use the versions and build configuration approved for the integration package.

dependencies {
    implementation "com.denovo:topliteapp-PROD:[SDK_VERSION]"
    implementation files("../libs/Cardcom-[AAR_VERSION]-Release_Prod.aar")
}

APK Finalization

Use the contents of the supplied AppFinalizationFolder.zip. Place the built APK, keystore.jks, and release.fin in the AppFinalizationFolder directory. Open CMD from that directory and run the steps in order:

Step A—Finalizer

finalizer -i APKFILE.apk -f release.fin -o finalizedApkFolder

Step B—Zip Align

zipalign -p -v 4 finalizedApkFolder\APKFILE-unaligned-unsigned-protected.apk finalizedApkFolder\APKFILE_aligned_unsigned.apk

Step C—Signing

apksigner sign --ks keystore.jks --ks-pass "pass:KEYSTOREPASSWORD" --out finalizedApkFolder\APKFILE_aligned_signed.apk finalizedApkFolder\APKFILE_aligned_unsigned.apk

Replace APKFILE with the actual file name and KEYSTOREPASSWORD with the keystore password. The password in the example is a placeholder. The final file for use is:

finalizedApkFolder\APKFILE_aligned_signed.apk

Perform this process for every new APK. Do not distribute the original file or intermediate files for TAP use; distribute only the final aligned and signed file.

Creating a JKS from a keystore, if required

When a keystore exists but no JKS file is available, use Java’s keytool, provide the source and destination passwords, and save the JKS file for signing:

keytool -importkeystore -srckeystore [file-name].keystore -destkeystore [file-name].jks -deststoretype jks

Generating SHA256 for manual distribution

keytool -alias [keystore-file-alias] -keystore [file-name].keystore -list -v

Replace the file name and alias with the actual values. In the output, locate Certificate fingerprints and send Cardcom the SHA256 value. For distribution through Google Play, obtain the value from Google Play Console, as instructed in the document.

13. Information to confirm with the technical contact

The sources provide the integration sequence and key fields but do not define all behaviors. An authoritative answer must be obtained before giving specific instructions or implementing the following:

The support checks and investigation recommendations in this article are practical explanations derived from the process sequence. They do not add a promise of support for an undocumented capability and do not establish a Cardcom escalation procedure or retry policy.

Up-to-date developer documentation is attached:

Only after reading the documentation, deciding to proceed with development, and purchasing a real terminal for testing.
Specific questions may be collected for discussion with Cardcom’s developer if needed, and a short call with the developer may be coordinated.

Attachments

• TAP Transaction Process via Cardcom Ltd (2).pdf