SDK on mobile

Our mobile solutions let you accept in-person payments on a mobile device, or on a card reader that is paired with a mobile device through Bluetooth.

• With the Tap to Pay solution, you start transactions from a POS app that runs on your mobile device and use the mobile device as the payment interface. Customers tap your mobile device with their payment card, or with their phone (or other device) that has a digital wallet like Apple Pay.

• With the card reader solution, you start transactions from a POS app that runs on your mobile device and use the card reader as the payment interface. Customers tap, insert, or swipe their card on the card reader, or use a digital wallet like Apple Pay.

If your POS app allows selecting the payment interface, you can use both solutions alongside each other.

Supported mobile devices

Adyen POS Mobile SDK

The starting point for mobile in-person payments is your iOS or Android POS app. This app must be integrated with our Terminal API. When you have such an app, you can build a mobile in-person payments solution by adding an iOS or Android Adyen POS Mobile SDK to the POS app. The Tap to Pay solution and the card reader solution use the same iOS SDK or Android SDK. For the card reader solution, the SDKs include functionality to manage the device pairing between your mobile device and the card reader.

Security of the SDK

Payments using the Adyen POS Mobile SDK are fully secure:

• Payment details that are read from the customer's payment method (card or digital wallet) are not kept locally on the phone or other mobile device.
• When using an iPhone as the payment interface for Tap to Pay on iPhone, transactions are encrypted and handled using Apple's Secure Element.
• The card reader is a PCI PTS-approved Secure Card Reader (SCR). When using the card reader as the payment interface, the payment details are encrypted immediately.
• The Adyen POS Mobile SDK sends and receives only encrypted payment messages.

Follow security best practices

To keep the solution secure, you must:

• Keep your API key secret and save it securely in your server.
• Never make requests to Adyen APIs directly from the POS app that is installed on the mobile device.

In addition, you should adhere to the following best practices:

• Follow the guidelines in our Integration security guide.
• Establish secure communications between your server and your POS app, using mutual authentication like mTLS.
  It is vital to prevent bad actors from modifying Terminal API transaction requests sent from your server to your app.
• Implement user authentication in your POS app, such as a login feature, to ensure only trusted users can operate the app.
• Keep the Adyen POS Mobile SDK updated to the latest version. After a short grace period, we do not accept transaction requests made using an older SDK version.
• Keep the Adyen POS Mobile SDK files secure: only get SDK files directly from trusted Adyen sources; when possible, validate the integrity of the SDK files; do not share SDK files with third parties.
• Keep the operating system on your mobile device updated to the latest version and the latest security patch.
• For internal development and testing only use the TEST version of the SDK.

Requirements for iOS

To integrate the SDK into your iOS POS app, you require:

• A POS app that is integrated with our Terminal API.
• An API credential with an API key, a client key, and the Checkout webservice role.
• Xcode version 15.3 or later.
• SDK version 3.2.0 or later.
• For Tap to Pay on iPhone: an entitlement on your Apple Developer account to use Tap to Pay on iPhone.

End users, like store staff, require the following:

• An iOS device with a device passcode set up to unlock it. For Tap to Pay on iPhone, the mobile device must be an iPhone Xs or later.

• The POS app, with the SDK integrated into it, installed on their mobile device.

• iOS version on their mobile device:

  iOS version on device with POS app	SDK integrated in the POS app
  iOS 17.0 or later	The device can use all functionality from the POS app, including the SDK functionality.
  iOS 13.0 - 16.x	The device can use the POS app, but not the SDK functionality.
  iOS 12.x or earlier	The device cannot run the POS app if the SDK is integrated into it.

• For the card reader solution, end users also need to have an NYC1 card reader from Adyen.

Requirements for Android

To integrate the SDK into your Android POS app, you require:

• A POS app that is integrated with our Terminal API.
• An API credential with an API key, a client key, and the Checkout webservice role.

In addition, you must provide your Adyen implementation manager with your app's package name and the corresponding certificate's SHA256 fingerprint.

End users, like store staff, require the following:

• An Android mobile device with the following features:

  • Must have an NFC reader.
  • Must be a commercial off-the-shelf device.
  • Must not be a payment terminal.
  • Must support hardware key attestation and be Google-certified. Before purchasing mobile devices, confirm with the manufacturer that the devices support hardware key attestation. The key attestation demo app can help rule out incompatibility.
  • Must have screen lock passcode configured on the device.
  • Can be updated easily to the latest Android version and security patch.

• The POS app, with the SDK integrated into it, installed on their mobile device.

• Android version on their mobile device: Android 11 updated to the latest security patch. The minimum required security patch is the one for March 5th 2022.

  Whenever Android stops supporting security patches for an OS version, the Android Adyen POS Mobile SDK no longer supports that OS version. Therefore, it is important to ensure your Android devices are easy to update, for example using Mobile Device Management (MDM) software.

• For the card reader solution, end users also need to have an NYC1 card reader from Adyen.

Current limitations

Integrations with the Adyen POS Mobile SDK have some limitations regarding payment features, payment methods, entry methods, and Cardholder Verification Methods (CVM).

Feature	Tap to Pay on Android	Tap to Pay on iPhone	Card reader
Payments
Offline payments			iOS only
Refunds, referenced
Refunds, unreferenced
Payment methods	Mastercard Visa	American Express Diners Discover eftpos Interac Mastercard Visa	American Express Mastercard Visa
Contactless
EMV
Magstripe
PIN			iOS only
Signature
Surcharge

Integration effort

Integrating the Adyen POS Mobile SDK obviously requires front-end development tasks. However, when planning the work, take into account the following.

• Back-end development tasks. You need to:

  • Implement a server-to-server call to set up a secure communications session between the SDK and 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.

• Cross-platform frameworks: integration of our native SDK into a cross-platform app is possible, but complex at the moment. We are working to improve the integration experience in cross-platform frameworks.

Test cards to use

To test transactions, you can use the following Adyen point-of-sale test cards:

• White-green test card
• Blue-green test card version 2.4 or later

The instructions are the same for both cards; see either of the pages mentioned above.

Build a solution

What solution do you want to build?