All modules

Tap On Phone Invocation SDK

The Tap On Phone Invocation SDK enables your application to integrate with ToPP Application

To complete a transaction using this SDK you should follow these steps:

Request the ToPP Identifier to ToPP application using this SDK.
Use that information along with the transaction related data to request a transaction intent to our services.
Send the transaction intent to this SDK to start a transaction flow.

For more details and advanced usage please read all methods documentation defined in this index. Also, please see classes javadoc for more detail

Requirements

Is a requirement to use this SDK to have installed in the device the ToPP application you want to invoque. The ToPP application will be launched by this SDK.

Setup

Add this to your buildScript repositories declaration

Maven repository

repositories {
    maven { url 'https://nexus.devops.geopagos.com/repository/android-geopagos_public/' }
}

And this to your module dependencies

SDK dependency

dependencies {
    implementation "com.geopagos.payments.taponphoneinvocation:topInvocationSdk:$topInvocationSdkVersion"
}

Initialization

First of all, SDK initialization is required:

TapOnPhoneInvocationSdk.init({CONTEXT}, {APPLICATION_ID})

Where:

CONTEXT is the ApplicationContext.
APPLICATION_ID is the application ID provided by Geopagos, which may include a suffix to identify different build types.

Request Application Data

To get Tap On Phone with PIN Application information you simply have to call:

TapOnPhoneInvocationSdk.requestApplicationData({CALLBACK})

Where:

CALLBACK: a function that receives an ApplicationDataSdkResult object as a parameter. This object represents the outcome of the request and can be either:

Success: contains the necessary data to create a Session Intent.
Error: contains a specific error type that needs to be handled appropriately.

Handling the Result

Here’s an example of how to handle the possible cases:

 TapOnPhoneInvocationSdk.requestApplicationData { applicationData ->
     when (applicationData) {
         is ApplicationDataSdkResult.Success -> TODO("ApplicationDataSdkResult Success")
         is ApplicationDataSdkResult.Error -> handleApplicationDataError(applicationData.error)
     }
 }

 fun handleApplicationDataError(error: ApplicationDataSdkError) {
       when (error) {
         is ApplicationDataSdkError.Connection -> TODO("ApplicationDataSdkError Connection")
         is ApplicationDataSdkError.DeveloperSettingsOn -> TODO("ApplicationDataSdkError DeveloperSettingsOn")
         is ApplicationDataSdkError.DeviceIsBlocked -> TODO("ApplicationDataSdkError DeviceIsBlocked")
         is ApplicationDataSdkError.Inaccessible -> TODO("ApplicationDataSdkError Inaccessible")
         is ApplicationDataSdkError.Internal -> TODO("ApplicationDataSdkError Internal")
         is ApplicationDataSdkError.KeyStore -> TODO("ApplicationDataSdkError KeyStore")
         is ApplicationDataSdkError.MessageNotSupported -> TODO("ApplicationDataSdkError MessageNotSupported")
         is ApplicationDataSdkError.SecurityError -> TODO("ApplicationDataSdkError SecurityError")
         is ApplicationDataSdkError.Timeout -> TODO("ApplicationDataSdkError Timeout")
         is ApplicationDataSdkError.Unknown -> TODO("ApplicationDataSdkError Unknown")
         is ApplicationDataSdkError.UpdateRequired -> TODO("ApplicationDataSdkError UpdateRequired")
       }
   }

ℹ️Info: On first usage if ToPP application is not loaded in memory this callback may have a delay around 5 seconds because of the security checks that are performed on first usage. You may receive a timeout on first usage, if this happen we recommend you to retry the request at least once.

💡Tip: To ensure a smooth transaction flow, it is recommended to initialize the SDK (TapOnPhoneInvocationSdk.init) and request the application data (TapOnPhoneInvocationSdk.requestApplicationData) as early as possible, ideally during the app initialization phase. This approach helps to reduce any delays or interruptions during the transaction process.

You still need to request the application data when starting the transaction in case the app data has changed (e.g. the ToPP app was updated). In case the app data hasn't changed, the response will be inmediate.

Get Session Intent

Once you have the ApplicationDataSdkResult you should use it to get the Session Intent.

Notes:

Any support needed to track issues will require the sessionId linked to the session that arises the issue. Please save this value for further assistance.

The session intent is generated with a request to https://[API_ENDPOINT]/api/v4/payments/tap-to-phone

This request MUST be performed by a Third Party Backend when a Third Party App requests it.

The most important part of the request is:

{
  "clientId": {
    "fingerprintId": "61:A2:0B:70:70:D2:DB:43:52:61:CB:75:E5:04:53:40:A8:38:7C",
    "applicationName": "geopagos",
    "applicationVersion": "1.0.0"
  }
}

If all provided data are valid the endpoint will answer a JSON object with the created session id and the encrypted session intent.

The values encrypted_data, hash and encrypted_key are required to start a transaction.

Notes: -Any support needed to track issues will require the sessionId linked to the session that causes the issue. -Please save this value for further assistance.

Start Transaction

Once you have the Session Intent to start the transaction, you need create an Activity Result Launcher with the function getTransactionContractWithToken()

val transactionActivity = registerForActivityResult(
  TapOnPhoneInvocationSdk.getTransactionContractWithToken()) { result ->
    handleResult(result)
  }

launch the transaction passing the session intent

transactionActivity.launch({SESSION_INTENT})

Where:

SESSION_INTENT is an instance of SdkSessionWithTokenIntent. Which containts the Session Intent data you retrieved in the previous step and an Authorization Token (this token can be the same as the used to Get a session intent.

And finally handle the result

fun handleTransactionResult() {
  when (result) {
        is TapOnPhoneInvocationSdkResult.Success -> TODO("Handle Transaction Success")
        is TapOnPhoneInvocationSdkResult.Error -> {
            when (result.error) {
                is TapOnPhoneInvocationSdkError.InvalidTransactionIntent -> TODO("Handle InvalidTransactionIntent")
                is TapOnPhoneInvocationSdkError.TransactionDenied -> TODO("Handle TransactionDenied")
                is TapOnPhoneInvocationSdkError.TransactionAborted -> TODO("Handle TransactionAborted")
                is TapOnPhoneInvocationSdkError.ConfigurationError -> TODO("Handle ConfigurationError")
                is TapOnPhoneInvocationSdkError.SecurityError.UpdateRequired -> TODO("Handle SecurityError - UpdateRequired")
                is TapOnPhoneInvocationSdkError.SecurityError.Other -> TODO("Handle SecurityError - Other")
                is TapOnPhoneInvocationSdkError.InternalError -> TODO("Handle InternalError")
                is TapOnPhoneInvocationSdkError.NfcNotAvailable -> TODO("Handle NfcNotAvailable")
                is TapOnPhoneInvocationSdkError.EULANotAccepted -> TODO("Handle EULANotAccepted")
            }
        }
    }
}

ℹ️Info: If you don't need the ToPP app to display any Payment Plans for user selection, you can use the getTransactionContract() method instead. This way you don't have to pass the Authentication Token. And launch the transaction activity passing in an instance of SdkEncryptedSessionIntent.

Release

When you no longer need to use the SDK, you must call

TapOnPhoneInvocationSdk.release()

This will release all resources used by the SDK. All objects retained after release() was called will no longer be valid. You can always init the SDK (as seen previously in this setup guide) to use it again after it was released.

Transaction Verification

When a transaction result is Success, it is a requirement to verify the transaction status via API prior to show the “approved” message to your user. This is to ensure the transaction state and avoid fraud attempts.

Call https://[API_ENDPOINT]/api/v4/payments/:ref_number/confirm

The ref_number param refers to the transaction reference number. And it is obtained when you Get a session intent.

All modules:

topInvocationSdk

tops-model