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
ApplicationDataSdkResultobject 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 ofSdkEncryptedSessionIntent.
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.