Understanding and using the SDK

The Samsung Pay SDK is an application framework for integrating selected Samsung Wallet features with Android-based partner apps on Samsung devices. The following major operations are supported:

In-App Payment Gives customers the option of paying for products and services with Samsung Wallet.
Push Provisioning Allows customers add a bank card to Samsung Wallet from the issuer app by providing the required card details.

To integrate your partner application with the Samsung Pay SDK, the following components are included your SDK download:

Samsungpay.jar Contains classes and interfaces of the Samsung Pay SDK which need to be integrated to partner apps.
Javadoc Provides descriptions of the APIs included in the Samsung Pay SDK, along with sample code showing how to use them.
Sample merchant app and sample issuer app showing how Samsung Pay APIs can be coded in a finished Android project. All major operations of Samsung Pay SDK are implemented for demonstration purposes.

Samsung Pay SDK architecture

The following diagram shows a high-level architecture revealing the general interactions between the Samsung Pay SDK and a partner app.

SDK high-level architecture

Viewed at this level, the partner apps leverage the Samsung Pay SDK to perform the operations shown ― push provisioning and opening Favorite Cards for issuers; online payments for merchants ― with Samsung Pay. The key components involved are:

Partner app - merchant- or issuer-developed app for making online/offline payments and provisioning payment cards through Samsung Wallet.
Samsung Pay SDK - SDK integrated into the partner app for direct communication with Samsung Wallet.
Samsung Wallet app - Wallet app that the Samsung Pay SDK communicates with.
Financial network - comprises the payment gateways, acquirers, card associations, and issuers that participate in transaction processing under agreement with the merchant.

The main classes comprising the Samsung Pay SDK include:

SamsungPay – used by the partner app to get the Samsung Pay SDK information and the status of Samsung Wallet app on the device.
PaymentManager – provides payment/transaction functionality .
CardManager – manages card list (get, add, update) functionality.
WatchManager – manages all functions related to Samsung Pay Watch.
CardInfoListener – interface for requestCardInfo result from Samsung Wallet.
CustomSheetTransactionInfoListener – interface for transaction success/failure callbacks from Samsung Wallet.

Use case: In-App Payment

The most common In-App (online) payment use cases take the following form:

Merchant app presents user with the option of making payment with Samsung Wallet.
Upon the user selecting the Samsung Pay option, the merchant app calls the APIs included in the Samsung Pay SDK to initiate a transaction with Samsung Wallet app.
Samsung Wallet app responds with the tokenized payment information necessary to complete the transaction.
Merchant app forwards this payment information to the designated Payment Gateway (PG), either directly through the merchant's web server, or indirectly via the Samsung-PG Interface server for normal transaction processing.

Use case: App-to-app

Push Provisioning

The push provisioning use case ― adding payment cards to Samsung Wallet from the card issuer’s app ― typically takes this form:

The user logs into the issuer app.
The issuer app checks if Samsung Wallet is activated on the device and ready to use. If it is in the ready status, the issuer app displays an Add button for cards not currently registered/enrolled with the Samsung Wallet app.
If the add card option is selected, the issuer app calls an API to push the proper payload data to Samsung Wallet.
While the card is being provisioned, Samsung Wallet stays in background.

Setting up SDK development environment

The importance of maintaining a good development environment cannot be overstated. For integrating the Samsung Pay SDK with your partner app, the following prerequisites and recommendations help ensure a successful SDK implementation.

System requirements

The Samsung Pay SDK is designed exclusively for Samsung mobile devices supporting Samsung Pay and running Android Lollipop 5.1 (Android API level 22) or later versions of the Android OS. The SDK’s In-App Payments functionality requires Android 6.0 (M) (Android API level 23) or later versions of the Android OS.

Note: As of SDK version 1.5, if the device runs Android Lollipop 5.1 (Android API level 22) or an earlier version, the getSamsungPayStatus() API method returns a SPAY_NOT SUPPORTED status code. Merchant apps still using Samsung Pay SDK 1.4 or earlier (not recommended) must check the Android version running their app.

Use the following snippet to determine the OS version running on a device and whether or not to display the Samsung Pay button in your partner 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
}

Service registration

To develop a Samsung Pay SDK service, merchants and issuers need to register for an account with Samsung Pay Developers in order to create the appropriate service type for their applications. Here are some helpful links inside the portal:

Become a member: https://pay.samsung.com/developers/tour/memberguide
Create services: https://pay.samsung.com/developers/tour/svcguide
Register apps: https://pay.samsung.com/developers/tour/appsguide
Manage services and apps: https://pay.samsung.com/developers/tour/svcnappsguide

Add Samsung pay SDK to your project

Be sure to do the following before attempting to use the SDK:

If not already part of your environment, download and install an IDE. Android Studio is recommended.
Download the Samsung Pay SDK

The SDK package has the following directory structure:

Folder	Contents
Docs	Javadoc – API reference documentation
Libs	samsungpay.jar SDK Java Archive file – contains the Samsung Pay APIs to be used by your partner app
Samples	Sample apps

Configure your IDE to integrate the Samsung Pay SDK with your partner app.

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

b) Go to Gradle Scripts > build.gradle and enter the following dependency:
```
dependencies {
    compile files('libs/samsungpay.jar')
}
```
c) Import the SDK package into your code
```
import com.samsung.android.sdk.samsungpay.v2;
```

ProGuard rules

If your app(s) have any issue with ProGuard, the following rules are recommended:

dontwarn com.samsung.android.sdk.samsungpay.** 
-keep class com.samsung.android.sdk.** { *; } 
-keep interface com.samsung.android.sdk.** { *; }

When DexGuard is employed, the following additional rules apply:

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

Android R OS (targetSdkVersion 30)

InformationFrom Android R OS (if the target SDK version is 30), you must include the following <queries> element in the Androidmanifest.

<?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>

Configuring API level

API level attributes

As of SDK version 1.4, enhanced version control management has been introduced to improve backward compatibility and handle API dependency from country and Service Type. For example, if a partner integrates the latest SDK―for instance, API level 2.21―but continues to use APIs based in level 1.4, the partner app remains compatible with Samsung Wallet apps supporting API level 1.4 without the necessity of upgrading the Samsung Pay app.

The chief characteristics and properties of the API level include:

Every API starting from version 1.4 has an API level assigned based on the SDK version number in which it is introduced.
The SDK’s Javadoc reference can be filtered by API level so you can determine the minimum API level you need to configure in the metadata section of your app’s AndroidManifest file. The earliest possible version is 1.4.
This lets you use the API level defined in your AndroidManifest without having to trigger an upgrade of the Samsung Wallet app on the user’s device.

Implement the following usage in your AndroidManifest:

<application
    ......
<meta-data
android:name="spay_sdk_api_level"
android:value="2.21" /> // most recent SDK version is recommended to leverage the latest APIs but it need to be set to 2.17 for Russia
    ......
    </application>

Partner app verification

In partner verification process Samsung Pay SDK verify your registered app, version in Samsung Pay portal and service. It also determines device and app compatibility. Your app needs to verify the presence of the Samsung Wallet app on the device, its status, and whether or not its version is sufficient to support your implementation of the SDK.

Partner verification flow

Appendix A. Common terminology

Terminology	Description
AAVS	Automatic Add Value Service
AIDL	Android Interface Definition Language for communication
Merchant	A business entity engaged in retail e-commerce that provides an online checkout service for purchasing its products and/or services to registered end users
Issuer	Financial institution empowered to issue credit and/or debit payment cards to qualified consumers and businesses
Payment Gateway (PG)	E-commerce app service provider equipped to authorize credit card payments for e-businesses, online retailers, bricks and clicks, or traditional brick and mortar
Payment Token	Secure method for payment ensuring that a cardholder’s information is not exploited by unauthorized parties
Samsung Pay	Samsung’s proprietary mobile wallet app and payment system
Samsung Pay Service	The server and service components of Samsung Pay
Samsung Pay Watch	Samsung Pay app on Samsung Galaxy Watches to support payment system
Eligibility Check	A query by third-party apps to check whether or not Samsung Pay is supported/activated/ready-to-use on a Samsung device
MST	Magnetic Secure Transmission
TUI	Trusted User Interface