Add the Adyen POS Mobile SDK for Android

To enable accepting payments through the Adyen POS Mobile SDK, take the following steps:

1. Add the Adyen POS Mobile SDK for Android to your Android project.
2. Add code to establish a session.
3. Add code to enable transactions through the Adyen POS Mobile SDK.

Add the SDK to your project

We provide the Adyen POS Mobile SDK for Android through a private Adyen repository. To get access, you need to have an Adyen API key that is used only for the purpose of getting the SDK.

For SDK versions earlier than version 1.6.0 it is possible to get access using a GitHub access token. However, we recommend using the API key method.

Establish a session

The Adyen POS Mobile SDK has to communicate in a secure way with the Adyen payments platform. To enable this, you must integrate a server-to-server POST /checkout/possdk/v68/sessions request to create a session. Your POS app needs to call your backend to trigger this request and get the session data.

The SDK uses the session data from the response to authenticate with our payments platform. Because the session expires after some time, the SDK checks regularly if it needs to establish a new session.

API key and roles

To authenticate your /checkout/possdk/v68/sessions requests, you need an API credential. This API credential must have an API key and a client key, and the following role:

• Checkout webservice role. This role is assigned by default when the API key is created.

Make a /sessions request

To let your backend establish a session:

1. From your backend, make a POST /checkout/possdk/v68/sessions request. In the request body, specify:

   Parameter	Required	Description
   merchantAccount		The unique identifier of your merchant account.
   setupToken		The setup token provided by the Adyen POS Mobile SDK for Android through the MerchantAuthenticationService.authenticate(setupToken) callback of MerchantAuthenticationService.
   store		The unique identifier of the store that you want to process payments for.

2. When you receive the response:

   • Check that you get a 201 Created HTTP status code.
   • Return the sdkData to your POS app.
   • If you create the Terminal API request on your backend, save the installationId and use this as the POIID in the MessageHeader of the payment request.

Going live

When going live, you must change the /sessions endpoint as well as the API key that you use to authenticate /sessions requests.

• To access the live endpoint, generate a new API key from your live Customer Area.

• The live endpoint URL contains a prefix which is unique to your company account, for example:

  https://{PREFIX}-checkout-live.adyenpayments.com/checkout/possdk/v68/sessions

  Get your {PREFIX} from your live Customer Area under Developers > API URLs > Prefix.

Enable transactions

To enable the payments functionality of the Adyen POS Mobile SDK for Android, add code to your Android POS app:

1. Implement the AuthenticationProvider interface. Note that you need to extract the sdkData from the server response and create an AuthenticationResponse object with sdkData in the constructor. Below is an example of how you could do that, assuming your project uses OkHttp.

   class MyAuthenticationProvider : AuthenticationProvider() {
   
       override suspend fun authenticate(setupToken: String): Result<AuthenticationResponse> {
   
           // Make a call to your backend to trigger a `/checkout/possdk/v68/sessions` request, specifying the `setupToken` provided by the SDK
   
           val client = OkHttpClient()
           val request = Request.Builder()
               .url("ADDRESS_OF_YOUR_BACKEND_API")
               .build()
   
           client.newCall(request).execute().use { response ->
               response.body?.let {
                   // parse your own back-end response and return AuthenticationResponse
                   ...
                   return Result.success(AuthenticationResponse.create(sdkData))
               }
           }
       }
   }

2. Implement the MerchantAuthenticationService abstract class: in your implementation, provide an instance of your AuthenticationProvider from the previous step. If you use Dagger2/Hilt dependency injection, below is an example of how you could do this:

   class MyAuthenticationService : MerchantAuthenticationService() {
   
       @Inject
       override lateinit var authenticationProvider: AuthenticationProvider
   }

3. Add the service to your POS app's AndroidManifest.xml file.

    <service android:name=".MyAuthenticationService"/>

4. Make sure that the MerchantAuthenticationService can provide new sdkData at any time.
   If there is no session or the session has expired, the service is called using the MerchantAuthenticationService.authenticate(setupToken) callback. Using the provided setupToken you need to get the sdkData through your backend and return it. For instructions, see Establish a session.

   The Adyen POS Mobile SDK detects the MerchantAuthenticationService automatically. If the SDK fails to detect the service, an error will occur when SDK methods are called. To resolve this, you can manually set the service using InPersonPayments.setAuthenticationServiceClass().

Manage automatic initialization

The Adyen POS Mobile SDK initializes automatically, using the the Android App Startup library. If you prefer to manually initialize the Adyen POS Mobile SDK, add the following code to the POS app's AndroidManifest.xml file to disable the Adyen POS Mobile SDK.

    <provider
        android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        tools:node="merge">
        <meta-data android:name="com.adyen.ipp.api.InPersonPaymentsInitializer"
                  tools:node="remove" />
    </provider>

To manually initialize that component at a later point, add the following code to the POS app.

    AppInitializer.getInstance(this)
                .initializeComponent(InPersonPaymentsInitializer::class.java)

Initialization status check

To check the status of the initialization you can use one of the two options below:

    InPersonPayments.initialised
      .filter { it } // Wait until it is true.
      .take(1)       // Take only one item.
      .collect { ready ->
        if (ready) {
          val id = InPersonPayments.getInstallationId()
          // ...
        }
      }

or

    InPersonPayments.initialised.filter { it }.take(1).single() // Suspends until it is true.
    val id = InPersonPayments.getInstallationId()

Manage POS app dependency initialization

The code that you add to the Application.onCreate() method is executed for all processes. In some cases, it can be beneficial to skip the re-execution of the code, for example the initialization of your dependency graph or analytics libraries.
The method below evaluates specific conditions and returns a boolean value that indicates whether the initialization should be skipped.

   if (InPersonPaymentsTools.shouldSkipAppInitialize(context)) {
       // Perform actions when initialization should be skipped

   } else {
       // Proceed with application initialization
   }

Next steps