Skip to main content

Integration guidelines

Overview​

The Tap on Phone Application (ToPP) is expected to be used as described in the Data Flow diagram using an SDK provided by Geopagos with its own documentation.

Basic integration​

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"
}
Download the Invocation SDK API documentation

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 is a function that receives ApplicationDataSdkResult as a parameter with the necessary information to start the transaction.
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.

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.

This request must have a header Authorization with a valid token provided to the Tenant. To generate this token, please refer to Authentication.

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 key encrypted_data and hash are required to start a transaction.

info

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.

For more information see the API reference

Start Transaction​

Once you have the Session Intent to start the transaction, you simply need to send it when launching the Tap On Phone Activity, and then handle the result as follows:

val transactionActivityResultLauncher = registerForActivityResult(TapOnPhoneInvocationSdk.getTransactionContract()) { result ->
    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")
            }
        }
    }

transactionActivityResultLauncher.launch({SESSION_INTENT})

Where:

  • SESSION_INTENT is an instance of SdkEncryptedSessionIntent, which wraps the Session Intent and it's hash.

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​

Once a transaction is confirmed by ToPS 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.

See the API reference for more information