Prerequisites for Samsung Pay SDK for Android

To use the Samsung Pay SDK for Android, make sure to meet the following prerequisites:

Check the device Android version

The Samsung Pay SDK for Android is designed exclusively for Samsung mobile devices that:

  • Support Samsung Pay.
  • Run Android Lollipop 5.1 (Android API level 22) or later.

If you are implementing the card transactions use case (managing customer's in-app payments through Samsung Pay), the Android 6.0 (M) (Android API level 23) or later is required. You need to check the device's Android version and hide the Samsung Pay button if the device version is too low:

  • Merchant apps using the Samsung Pay SDK for Android version 1.5 must use the getSamsungPayStatus() method. If a device is running Android Lollipop 5.1 (Android API level 22) or earlier, the method returns the SPAY_NOT SUPPORTED status code.

  • Merchant apps using the Samsung Pay SDK for Android version 1.4 or earlier (not recommended) must manually check the Android OS version running their app.

    import android.os.Build; 
// In-App payment supported on Android M or above 
// Check Android version of the device
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
    // Hide Samsung Pay button
}

Add the Samsung Pay SDK for Android to your project

To use the Samsung Pay SDK for Android:

  1. If you do not have one set up already, download and install the IDE of your choice.

    Android Studio is recommended.

  2. Download the Samsung Pay SDK for Android.
    The SDK package has the following directory structure:

    Folder

    		 Content
    Docs

    		 Javadoc: API reference documentation containing descriptions of the APIs included in the SDK
    Libs

    		 samsungpay.jar: SDK Java archive file that contains the Samsung Pay APIs to be used by your app
    Samples

    		 Sample apps demonstrating how you can implement Samsung Pay APIs in your app

  3. Configure your IDE to integrate Samsung Pay with your app:

    1. Add samsungpay.jar to the libs folder of your Android project.

    2. Enter the Samsung Pay dependency in the build.gradle script.

      dependencies {
  compile files('libs/samsungpay.jar')
}

    3. Import the SDK package into your code.

      import com.samsung.android.sdk.samsungpay.v2;

    4. If your app has any issues related to ProGuard code optimization, implement the following rules in debug mode:

      dontwarn com.samsung.android.sdk.samsungpay.**  
-keep class com.samsung.android.sdk.** { *; }  
-keep interface com.samsung.android.sdk.** { *; } 
-keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level 
-keepresourcexmlelements manifest/application/meta-data@name=debug_mode 
-keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key

      If you are using DexGuard to secure your source code, apply the following additional rule:

      -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level

    5. Starting from Android R OS (if the Android OS target SDK version is 30), include the following <queries> element in the AndroidManifest.xml file.

      <?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="xxx.xxx.xxx.xxx">
   <queries>
        <package android:name="com.samsung.android.spay" />
        <package android:name="com.samsung.android.samsungpay.gear" />
   </queries>

Configure the Samsung Pay API level

Starting from the Samsung Pay SDK for Android version 1.4, enhanced version control management improves backward compatibility and handles API dependency based on country and service type. For example, if you integrate the latest SDK ― for example, version 2.22 ― but continue to only use APIs based on version 1.4, your app remains compatible with the Samsung Wallet apps supporting version 1.4 without needing to upgrade the Samsung Wallet app.

The enhanced version control works as follows:

  • Every API starting from the Samsung Pay SDK for Android version 1.4 has an API level assigned to it, reflecting the SDK version. Set this level in the metadata section of your app’s AndroidManifest.xml file.
  • You can filter the Samsung Pay SDK for Android’s Javadoc reference by API level to determine your app's minimum API level based on the SDK features you are using. The minimum possible API level is 1.4.
  • Setting the minimum API level in your AndroidManifest.xml file allows your app to use the defined API level without having to trigger an upgrade of the Samsung Wallet app on the customer’s device.

To set the minimum API level, implement the following code snippet in your AndroidManifest.xml file:

<application>
    ...
<meta-data
android:name="spay_sdk_api_level"
android:value="2.22" /> // Most recent SDK version is recommended as the API level to leverage the latest APIs, but for Russia, 2.17 needs to be set instead
    ...
</application>