Point-of-sale icon

Add the Adyen POS Mobile SDK for Android

Update your code to integrate the Adyen POS Mobile SDK in your Android POS app.

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

  1. Add the Adyen POS Mobile SDK for Android to the Android Studio (or other) project that contains your Android POS app.
  2. Add code to establish a session.
  3. Add code to enable transactions through the Adyen POS Mobile SDK.

Add the Adyen POS Mobile SDK

We provide the Adyen POS Mobile SDK for Android through GitHub Packages, using a private GitHub repository. To get access, you need to create a single access token for your company.

  1. Provide your Adyen contact with the username of the personal GitHub account that your company will use for generating an access token to the remote repository where the SDK is stored.

    We will add one GitHub account per company to our repository.

  2. Generate a classic personal access token:

    1. Log in to GitHub with the username provided to Adyen.
    2. Go to https://github.com/settings/tokens and select Generate new token > Generate new token (classic).
    3. Select only the read:packages scope and then select Generate token.
    4. Copy the token to a secure location.

    You can share the token with anybody in your team who needs to get the SDK.

  3. Remove any existing, old SDK files from your local Maven /.m2/repository/ folder.

  4. In your project's build.gradle file, add the package dependencies.

    releaseImplementation 'com.adyen.ipp:pos-mobile-release:$version'
debugImplementation 'com.adyen.ipp:pos-mobile-debug:$version'
    • The -debug version can only access the Test environment and the -release version can only access the Live environment.
    • In case of other custom build variants, use <buildVariantName>Implementation 'com.adyen.ipp:pos-mobile-<type>:$version' where <type> can be release (for production builds) or debug (for debug or development builds).

  5. In the repositories block of the build.gradle file, add the URL to the remote repository where the SDK is stored, the GitHub username provided to Adyen, and the GitHub token that was created for that user.

    repositories { 
    maven { 
        url = uri("https://maven.pkg.github.com/Adyen/adyen-pos-mobile-android-artifacts") 
        credentials { 
            username = "GITHUB_USER_NAME" 
            password = "GITHUB_CLASSIC_PERSONAL_ACCESS_TOKEN" 
        } 
    } 
}

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 /checkout/possdk/v68/sessions request to create a session. Your POS app needs to call your backend to trigger this /sessions request and get the session data.

The SDK uses the session data from the /sessions 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 /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.

Going live

When going live, you need to change the endpoint as well as your API key:

  • To access the live endpoint, generate an 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.

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:

    • merchantAccount: the unique identifier of your merchant account.
    • store (optional): the unique identifier of the store that you want to process payments for.
    • setupToken: the setup token provided by the Adyen POS Mobile SDK for Android through the AuthenticationService.authenticate(setupToken) callback of AuthenticationService.

  2. From your backend, make a POST /checkout/possdk/v68/sessions request, specifying:

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

  3. 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.

Enable transactions

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

  1. Initialize the Adyen POS Mobile SDK (possibly in your own Application.onCreate()).

    InPersonPayments.initialize(application = application)

  2. 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 `/sessions` request, supplying the provided `setupToken`

        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(sdkData))
            }
        }
    }
}

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

    class MyAuthenticationService : AuthenticationService() {

    @Inject
    override lateinit var authenticationProvider: AuthenticationProvider
}

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

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

  5. Make sure that the AuthenticationService can provide new sdkData at any time.
    If there is no session or the session has expired, the service is called using the AuthenticationService.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.

Next steps