To enable accepting payments through the Adyen POS Mobile SDK, take the following steps:
- Add the Adyen POS Mobile SDK for Android to your Android project.
- Add code to establish a session.
- 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 a private Adyen repository. To get access, you need to create an API key in the Customer Area.
Our SDK will only run on Android 11 or later. You can still target lower Android SDK versions, but the SDK will not initialize.
We recommend to add the Adyen POS Mobile SDK for Android with a token that you generate in your Customer Area. It is still possible to add versions of the SDK earlier than version 1.6.0 with a GitHub access token.
-
In your Customer Area create an API credential with an API key:
- Go to Developers > API credentials, and select Create new credential.
- Under Payments > Credential type select Web service user and then select Create credential.
- Under Server settings > Authentication select the API key tab and the select Generate API key.
- Select the copy icon and store your API key to a secure location.
- Go to Permissions > Roles > POS and select Allow SDK download for POS developers.
Contact Support Team if you don't see the Allow SDK download for POS developers role.
- Select Save changes.
You can share the API key with anybody in your team who needs to get the SDK or create multiple API keys for internal use.
-
In the
repositories
block of your project, usually defined in yoursettings.gradle
file, add the URL to the remote repository where the SDK is stored and the API key that you created in the Customer Area.dependencyResolutionManagement { //... repositories { google() mavenCentral() maven { url = uri("https://pos-mobile-test.cdn.adyen.com/adyen-pos-android") credentials(HttpHeaderCredentials::class) { name = "x-api-key" value = "<YOUR_API_KEY>" } authentication { create<HttpHeaderAuthentication>("header") } } } } -
In your project's
build.gradle
file, add the package dependencies.To find the latest
val version
check the Android mobile SDK release notes.val version = 1.5.0 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).
- The
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.
Going live
Before going live, you need to make changes to your integration. Depending on what type of token you are using, select the tab below that applies to you.
When going live, you will need the release version of the SDK, which is available on the live repository. To access it, change the repository URL as well as your API key:
-
To pull in the live version of the SDK:
- Generate a new API key in your live Customer Area.
- In your project's
build.gradle
file change theURL
tohttps://pos-mobile.cdn.adyen.com/adyen-pos-android
and replaceAPI_KEY
with your new Api key. - Add the
release
dependency to yourbuild.gradle
file:
val version = 1.5.0 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. - The live repository has both the
debug
andrelease
artefacts. When you have access to the live repository, you no longer need to use the test repository. - 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).
- 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:
-
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 ofMerchantAuthenticationService
.store The unique identifier of the store that you want to process payments for. /sessions requestExpand viewCopy link to code blockCopy codecurl https://checkout-test.adyen.com/checkout/possdk/v68/sessions \ -H 'content-type: application/json' \ -H 'x-API-key: ADYEN_API_KEY' \ -X POST \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "setupToken": "SETUP_TOKEN", "store": "YOUR_STORE_ID" }' -
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 theMessageHeader
of the payment request.
/sessions responseExpand viewCopy link to code blockCopy code{ "id": "APP_SESSION_ID", "installationId": "INSTALLATION_ID", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "store": "YOUR_STORE_ID", "sdkData": "SDK_DATA_BLOB" }
Enable transactions
The Adyen POS Mobile SDK initializes automatically, using the the Android App Startup library. It is possible to disable the automatic initialization of the POS Mobile SDK if needed. If you are unsure of the status of the POS Mobile SDK initialization you can run a status check.
To enable the payments functionality of the Adyen POS Mobile SDK for Android, add code to your Android POS app:
-
Implement the
AuthenticationProvider
interface. Note that you need to extract the sdkData from the server response and create anAuthenticationResponse
object withsdkData
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(sdkData)) } } } } -
Implement the
MerchantAuthenticationService
abstract class: in your implementation, provide an instance of yourAuthenticationProvider
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 } -
Add the service to your POS app's
AndroidManifest.xml
file.<service android:name=".MyAuthenticationService"/>
-
Make sure that the
MerchantAuthenticationService
can provide newsdkData
at any time.
If there is no session or the session has expired, the service is called using theMerchantAuthenticationService.authenticate(setupToken)
callback. Using the providedsetupToken
you need to get thesdkData
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 usingInPersonPayments.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.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 }