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.
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.
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:
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.
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
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.