Android Payments app

If you want to accept Tap to Pay payments on your Android mobile device but do not want to integrate our POS Mobile SDK, you can download the Adyen Payments app from the Google Play store. You can then use the Payments app to connect your own POS app to the Adyen payments platform and authenticate payment requests in a compliant way.

The way you implement Tap to Pay on Android depends on your use case and development capabilities. You may prefer a low-code integration that does not include the PCI MPOC certification scope or a more involved integration that allows more control of the app experience. Both integration paths require a Terminal API integration.
For an overview of benefits of each integration path, see the following table:

Integration effort

Integrating the Tap to pay flow using the Adyen Payments app requires some development tasks from your side. When planning the work, take into account the following.

• Back-end development tasks. You need to:
  • Board the Adyen Payments app on every Android mobile device where you installed it.
  • Implement a server-to-server call to set up a secure communication session between your POS app on an Android mobile device and your back-end. You then make API calls from your back-end to the Adyen payments platform.
  • Integrate your POS app with Terminal API. You must support the PaymentRequest , and preferably also the ReversalRequest .

    How to integrate with Terminal API is described in other sections of our documentation.

How it works

1. Your Android POS app creates a Terminal API payment request, or receives a Terminal API payment request from your back-end.
2. Your Android POS app sends an encrypted, Base64URL-encoded Terminal API payment request to the Payments app as a deep link with your return URL.
3. A Tap to Pay screen shows, and the shopper presents their contactless payment method to the NFC reader of your Android mobile device.
4. The Payments app routes the payment request through our POS Mobile SDK to the Adyen back-end.
5. The Adyen back-end returns an encrypted, Base64URL-encoded Terminal API payment response to the Payments app.
6. The screen shows the outcome, switches to your POS app using the return URL you specified. Your POS app receives the encrypted, Base64URL-encoded Terminal API payment response.

Requirements

Before you begin building a test integration:

• Make sure that you have a test account
• Create a new API key specifically for the Adyen Payments app with:
  • Client key generated for that API key under Client settings > Authentication > Client key
  • The Adyen Payments app role configured by our Support Team
• Order either a Blue-green (v2.4 or higher) or a White-green Adyen test card
• Download the Adyen Payments Test app from the Google Play store
• Enable Tap to Pay on Android with Adyen
• Optionally, configure unreferenced refunds with Adyen
• Read the Android app requirements and current limitations
• Enable a passcode on your Android mobile device

Step 1: Start boarding the app

After you download the Payments app form the Google Play store, you need to board it. To start the boarding flow, you call a deep link from your POS app to check if the Adyen Payments app is already boarded:

1. Call the deep link from your POS app. The deep link contains:

   • Base URL: adyenpayments-test://boarded.
   • returnUrl: the URL-encoded base URL where you want to receive the response. We will call your return URL with Action type Intent.ACTION_VIEW.

2. Check the response and decide what to do next. The response consists of the returnUrl you specified in the deep link, and the following parameters:

   Parameter	Required	Type	Description
   Base URL		URL	The URL-encoded base URL where you want to receive the response. This is the returnUrl you specified in the request.
   boarded		Boolean	Indicates if the app is boarded or not.
   installationId		String	The unique identifier of the Payments app instance on the specific device. When creating Terminal API requests on your back-end, use this as the POIID in the MessageHeader of the request.
   boardingRequestToken		String	The app token used to request the boardingToken from Adyen.

3. Depending on the response, proceed as follows:

   • If boarded is true: pass installationId to your back-end and proceed to making a payment. You do not need to continue with the boarding flow.
   • If boarded is false: pass the installationId and boardingRequestToken to your back-end and proceed to Step 2 of the boarding flow.

Step 2: Authenticate the app installation

If you determined in Step 1 that the Payments app is not boarded yet, you need to get a boardingToken by making a Payments app API request to Adyen. You only need to authenticate the app instance once.

To make this request to Payments app API, you need to have an API credential with an API key that includes a client key, and the following roles:

• Adyen Payments App role user role

Depending on whether you want to accept payments using your merchant account or a store, to authenticate the app:

1. Make either a POST /merchants/merchantId/generatePaymentsAppBoardingToken or /merchants/merchantId/stores/storeId/generatePaymentsAppBoardingToken, specifying:

   • Path parameters:

   Parameters	Required	Description
   merchantId		The unique identifier of the merchant account.
   storeId		The unique identifier of the store. The storeId is not the same as store reference. If you only know the reference, you can use it to get the storeId with an API call.

   • Request parameters:

   Parameters	Required	Description
   boardingRequestToken		The app token used to request the boardingToken from Adyen. You received this in Step 1.

2. If successful, the response returns:

   Parameter	Required	Type	Description
   installationId		String	The unique identifier of the Payments app instance on the specific device.
   boardingToken		String	The one-time token used to authenticate the app installation. Valid for 1 hour.

Step 3: Finish boarding the app

Once your POS app gets the boardingToken from Adyen, you need to send it to the Payments app to finish boarding the app and prepare for making payments.

To finish boarding the app:

1. Call the deep link from your POS app. The deep link contains:

   • Base URL: adyenpayments-test://board.
   • boardingToken: the token generated for this installationId by Adyen in Step 2. This token must be Base64URL-encoded.
   • returnUrl: a URL-encoded base URL where you want to receive the response. We will call your return URL with Action type Intent.ACTION_VIEW.

2. Check the response and decide what to do next. The response consist of the returnUrl you specified in the deep link, and the following parameters:

   Parameter	Required	Type	Description
   Base URL		URL	The URL-encoded base URL where you want to receive the response. This is the returnUrl you specified in the request.
   boarded		Boolean	Indicates if the app is boarded or not.
   installationId		String	The unique identifier of the Payments app instance on the specific device. When creating Terminal API requests on your back-end, use this as the POIID in the MessageHeader of the request.
   error		String	Additional information in case an error occurs.

3. Depending on the response, proceed as follows:

   • If boarded is true: pass installationId to your back-end and proceed to making a payment. You do not need board the app again.
   • If boarded is false: check the error and try again.

Make a payment

After the Payments app is boarded, you are ready to make payments. To do this you need to create a Terminal API payment request in the Base64URL format as deep link and call it from your POS app. The boarded Payments app then communicates with Adyen, receives the response and returns it in Base64 as part of a deep link to your POS app.

To start a payment from your POS app:

1. Create a Terminal API payment request.

   The POIID value must be set to the installationId value of the boarded Payments app.

2. Encrypt the Terminal API request as described for a local Terminal API integration.

3. Encode the payment request to Base64URL.

4. Call the deep link from your POS app. The deep link contains:

   • Base URL: adyenpayments-test://nexo.
   • request: Base64URL-encoded Terminal API payment request.
   • returnUrl: a URL-encoded base URL where you want to receive the response. We will call your return URL with Action type Intent.ACTION_VIEW.

5. You can use the response to show details in your POS app. The response consist of the returnUrl you specified in the deep link, and the following parameters:

   Parameter	Required	Type	Description
   Base URL		URL	Your returnUrl.
   response		String	Base64URL-encoded and encrypted Terminal API payment response.
   error		String	Additional information in case an error occurs.

   If the shopper does not present their payment method within 30 seconds, the payment request times out. If that happens, you need to make another payment request.

Revoke app installation

If your Android mobile device is defective, stolen, or you do not need it anymore for payments processing, you can stop the Payments app from processing transactions with Adyen. To do this, you make an API call to Adyen to revoke the specified installationId.

To make this request to Payments app API, you need to have an API credential with an API key and the following roles:

• Adyen Payments app role user role

To revoke a boarding token:

1. Optionally, make either a GET /merchants/merchantId/paymentsApps or /merchants/merchantId/stores/storeId/paymentsApps request to retrieve the list of Payments app instances for a merchant account or a store. You can then use the installationId to revoke boarding tokens.

2. Make an POST /merchants/merchantId/paymentsApps/installationId/revoke API call and specify:

   • As path parameters:

   Parameters	Required	Description
   installationId		The unique identifier of the Payments app instance on the specific device.
   merchantId		The unique identifier of the merchant account.

3. If successful, the response returns 200 OK.

Go live

When you have finished testing your integration and are ready to go live, make sure you:

• A live account
• A new API key specifically for the Adyen Payments app with the Adyen Payments app role configured
• Downloaded the Payments app from the Google Play store
• Enabled Tap to Pay on Android with Adyen
• Optionally, configured unreferenced refunds with Adyen
• Read the Android app requirements
• Enabled a passcode on your Android mobile device
• Use the live base URLs for deep links:
  • adyenpayments://boarded
  • adyenpayments://board
  • adyenpayments://nexo
• Use the live Management API endpoints:
  • https://management-live.adyen.com

Verify app instance

Adyen continuously checks if the app instance on your Android mobile device is authentic. This is to protect your integration against man-in-the-middle attacks, eavesdropping, and tampering. You can also check this yourself manually using a different device and your email address.

To verify the app instance, in the Payments app:

1. Go to Settings and tap Verify app.
2. Enter your email address and tap Send email.
3. Check your email on another device. You should have received an email with a 5-character code.
4. In the Payments app, if you received the email, tap Continue. If you did not receive the email, check the email address you entered, and tap Resend email and go back to step 2.
5. Under Verify app, check that the 5-character code on the screen matches the code you received in the email.

If the app instance verification is successful, you can continue making payments with the Payments app. If the verification fails, Adyen automatically revokes the app instance. In this case, you need to board the app again on that Android mobile device.

See also