Overview

This guide is intended for merchant/issuer app developers familiar with the Android programming environment and APK ecosystem. In accordance with the applicable Samsung partner agreements, it covers the setup and use of the Samsung Pay SDK for purposes of integrating the Samsung Pay app with partner apps developed by both merchants and payment card issuers for Samsung devices and is intended for no other purpose. The use cases and corresponding code samples included are representative examples only and should not be construed as either recommended or required. For APIs and sample code reference, the latest Javadoc of the Samsung Pay SDK is recommended.

Please be aware that, due to regulatory restrictions in different countries, certain Samsung Pay APK behavior designed for one country may not be identical to one for another country. Always use the Samsung and Samsung Pay documentation applicable to the market you are working in and test your integrated project in accordance with the guidance provided for that market/country.

Understanding and using the SDK

The Samsung Pay SDK is an application framework for integrating selected Samsung Pay 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 Pay.
Push Provisioning Allows customers add a bank card to Samsung Pay 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 Pay.
Samsung Pay SDK - SDK integrated into the partner app for direct communication with Samsung Pay
Samsung Pay app - Pay 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 Pay 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 Pay.
CustomSheetTransactionInfoListener – interface for transaction success/failure callbacks from Samsung Pay.

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 Pay.
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 Pay app.
Samsung Pay 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

The most common App-to-App (also referred to as App2App) use cases can be divided into three categories:

Push Provisioning

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

The user logs into the issuer app.
The issuer app checks if Samsung Pay 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 Pay app.
If the add card option is selected, the issuer app calls an API to push the proper payload data to Samsung Pay.
While the card is being provisioned, Samsung Pay 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=debug_mode 
-keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key 
-keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level

Android R OS(rargetSdkVersion 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 debug mode

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.17―but continues to use APIs based in level 1.4, the partner app remains compatible with Samsung Pay 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 Pay 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.17" /> // most recent SDK version is recommended to leverage the latest APIs
...... 
</application>

Debug and Release mode

Apps configured for one of two modes can be registered in the Samsung Pay Developers site for the purpose of integrating Samsung Pay functionalities.

Debug mode – for testing and QA; requires debug key and allowed Samsung account(s) in build in order to test.
Release mode – for market release to end users; does not need a debug key or an allowed list of Samsung accounts in a Samsung-approved build to run.

Debug mode
To enable debug mode, you must add debug_mode and spay_debug_api_key to your AndroidManifest.xml file. The spay_debug_api_key is generated by the Samsung Pay Developers portal when you create a new In-App payments service.

The spay_debug_api_key is valid for 90 days and can be updated on the Samsung Pay Developers portal.

<application 
   ...... 
   <meta-data 
      android:name="debug_mode" 
      android:value="Y" /> 
   <meta-data 
      android:name="spay_debug_api_key" 
      android:value="asdfggkndkeie17283094858" /> 
   ...... 
</application>

Release mode
To enable release mode, set debug_mode = N in your AndroidManifest.xml file.
With release mode enabled, your partner app is verified by its signature instead of a spay_debug_api_key, and there is no time limit.

<application 
...... 
   <meta-data 
      android:name="debug_mode" 
      android:value="N" /> 
...... 
</application>

Partner app verification

Depending on the mode configured—Debug or Release—verification of your registered app and service by the Samsung Pay SDK and its Developers portal entails version and eligibility checks to determine device and app compatibility. Likewise, your app needs to verify the presence of the Samsung Pay app on the device, its status, and whether or not its version is sufficient to support your implementation of the SDK.

Partner verification flow

The debug mode set in your Partner app allows for simplified verification as shown in the following table.

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