Setup the SDK

Your application communicates with the Soft Point-of-Sale app using the App2App library, to execute the following actions:

  • Payment
  • Reversal
  • Reconciliation

Communication between applications uses Android Intents with encrypted payload. This data is based on Nexo Retailer Protocol.

Communication between library and Soft Point-of-Sale App is encrypted with a pre-shared 128 bit symmetric key.

How the SDK should be used

The SDK is also called App2App.

The App2App library needs to be a part of your app. All messages are sent and received through Client class object.

Requests are sent in intents, which start a service in the Soft Point-of-Sale App.

Responses are intents, received in application’s service or activity, and handled by Client class.

It is the responsibility of your application to create a service / activity which will handle incoming intents from Soft Point-of-Sale app, and pass them to Client class object.

Before your app is ready to send payment:

  • Client object needs to receive authorization data from your app.
  • Soft Point-of-Sale app needs to be provisioned through Client object or manually

Getting started

To make use of the App2App library you need to complete the following steps:

  1. Extend the Client() class and override the onResponse() and onResponseError() methods
  2. Instantiate a new instance of your extended class
  3. Set the api key
  4. Set the provision status listener
  5. Set Intent Filter
  6. Set the provision data
  7. Perform provisioning

Step 1 - Extend Client

The first step is to extend the main interaction class Client. Extending this class allows access to the onResponse and onResponseError methods which are used to inspect the results of payment actions. An example extension of Client is as follows:

class ClientImplementation(
        context: Context
    ):
    Client(context, sha256OfSigningCertificate) {
        override fun onResponse(xmlResponse: String) {
            super.onResponse(xmlResponse) 
            Log.d(LOG_TAG, xmlResponse)
        }
        override fun onResponse(response: RTRSaleToPOIResponse) {
            super.onResponse(response)
            Log.d(LOG_TAG, response.toString())
        }
        override fun onResponseError(errorCode: Int) {
            super.onResponseError(errorCode)
            Log.d(LOG_TAG, "onResponseError: errorCode: $errorCode")
        }
    }

Step 2 - Initialize Client

To use the library the next step is to initialize the extended implementation of Client and set the api key with Set API key and provisioning status listener (the listener is a class that implements Client.ProvisionStatusCheckListener):

var client = ClientImplementation(context, sha256OfSigningCertificate) 
client.setProvisionStatusListener(this) 
client.setApiKey(apiKey)

The signing certificate needs to match value in authorization triple in Scap config. It is needed for communication encryption.
Note: In the provided demo app the signing certificate and API key are both provided in Config.kt.'

Step 3 - Set the provision data

Provide the provisioning user information with the Set provision data method. Data received by client through setProvisionData() is stored in client app’s preferences.

Step 4 - Perform provisioning

Afterwards, invoke the provisioning process with provision to send the data to Soft Point-of-Sale app. This sends data which was set via setProvisionData() along with sender’s app package and sha256 of encryption key. The intent is received by the Intent Filter and processed by client.onResponseIntent(intent).

Once completing this process, the library is now initialized and ready to be used with the payments methods documented towards the end of this document.