Samsung Pay

MeaPushProvisioning.SamsungPay helper interface provides methods to interact with Samsung Pay wallet.

Samsung Pay Push Provisioning API documentation:

• Samsung Pay SDK download
• Samsung Pay SDK - Push Provisioning
• App to App card enrollment integration guide

info

If your App targets Android 11 or higher, add the <queries> element in the App manifest:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.app">
    ...
    <queries>
        <package android:name="com.samsung.android.spay" />
        <package android:name="com.samsung.android.samsungpay.gear" />
    </queries>
    ...
</manifest>

See Package visibility filtering on Android.

Set Service ID

You must pass Samsung Pay ServiceId (SID) to MPP SDK before using MeaPushProvisioning.SamsungPay API.

MeaPushProvisioning.SamsungPay.setServiceId("partner_app_service_id");

info

Service Id is assigned by the Samsung Pay Developers portal when you create the service.

Get Status

The first step check Samsung Pay status on the device to determine its support for Samsung Pay. Issuer app must call this Method to check the current status of Samsung Pay before doing any operation. If the status is SAMSUNG_PAY_SETUP_NOT_COMPLETED or SAMSUNG_PAY_APP_NEED_TO_UPDATE, issuer application can activate the Samsung Pay app on the device and update it to the latest version.

MeaPushProvisioning.SamsungPay.getStatus(new SamsungPayStatusListener() {
    @Override
    public void onSuccess(SamsungPayStatus samsungPayStatus) {
        try {
            switch (samsungPayStatus) {
                case SAMSUNG_PAY_READY:
                    // Samsung Pay is properly activated and ready to use
                    break;

                case SAMSUNG_PAY_SETUP_NOT_COMPLETED:
                    MeaPushProvisioning.SamsungPay.activatePay();
                    break;

                case SAMSUNG_PAY_APP_NEED_TO_UPDATE:
                    MeaPushProvisioning.SamsungPay.update();
                    break;

                case SAMSUNG_PAY_NOT_SUPPORTED:
                case SAMSUNG_PAY_UNEXPECTED_STATUS:
                case SAMSUNG_PAY_NOT_READY:
                    // Not supported or unexpected error
                    break;
            }
        } catch (MppException exception) {
            // ...
        }
    }

    @Override
    public void onFailure(@NonNull MppError error) {
        // called when the requested operation fails
    }
});

Push Card

When MPP SDK is initialized, Issuer app can push provision card using MeaPushProvisioning.SamsungPay.pushCard(...) and MppCardDataParameters. This method checks the state of Samsung Pay wallet and creates a new instance when necessary. Backend generated opaque payment card (OPC) is received, and if the specific card is not added to Samsung Pay wallet already, it pushes the card to the Samsung Pay wallet via Samsung Push Provisioning API.

MeaPushProvisioning.SamsungPay.pushCard(cardParams, getActivity(), new MppPushCardToSamsungPayListener() {
    @Override
    public void onSuccess(String tokenId, String cardLastFourDigits, MppPaymentNetwork cardNetwork) {
        ...
    }

    @Override
    public void onFailure(MppError mppError) {
        ...
    }
});

Add to Samsung Pay Button

The Add to Samsung Pay button is used exclusively to initiate the Samsung Pay card provisioning flow from an Issuer app. The "Add to Samsung Pay" and other buttons are available as .png and .ai images: Branding guideline / Buttons Assets

Show or Hide Add to Samsung Pay Button

App is responsible to check and decide if "Add to Samsung Pay" should be shown or hidden for the user. Button should be shown only when card is not added to Samsung Pay already. MPP SDK provides 2 methods to check if the corresponding card for a token is available in Samsung Pay active wallet:

• MeaPushProvisioning.SamsungPay.checkWalletForCardToken(MppCardDataParameters cardData, SamsungPayTokenListener listener) - using card data, requires network connection.
• MeaPushProvisioning.SamsungPay.checkWalletForToken(MppPaymentNetwork paymentNetwork, String tokenId, SamsungTokenListener listener) - using pre-fetched token data.

If card exists in Samsung Pay wallet, both methods return SamsungPayTokenInfo that contains information about the specific Samsung Pay token, use getTokenId(), getTokenState(), getPaymentNetwork() and isSelectedAsDefault() methods to get the values. Issuer app should hide "Add to Samsung Pay" button when card exists in Samsung Pay wallet. If methods above return null, Issuer app should show "Add to Samsung Pay" button.

Use SamsungPayTokenInfo.getTokenState() to get additional info about the token state.

Method MeaPushProvisioning.SamsungPay.checkWalletForCardSuffix(String cardSuffix, SamsungPayRegisteredTokensListener listener) can be used to get token(s) with matching PAN suffix.

MeaPushProvisioning.SamsungPay.checkWalletForCardSuffix(CARD_LAST_FOUR_DIGITS, new SamsungPayTokenInfoListListener() {
    @Override
    public void onSuccess(@NonNull List<SamsungPayTokenInfo> tokens) {
        for(SamsungPayTokenInfo tokenInfo : tokens) {
            // Hide "Add to Samsung Pay" button.
        }
    }

    @Override
    public void onFailure(@NonNull MppError mppError) {
        // Handle error
    }
});

Managing Default NFC Payment App

Issuer app can check if Samsung Pay is set as default NFC payment app after push provisioning a card. This allows users to pay with Samsung Pay using their new cards. Check if Samsung Pay is set as default NFC payment app:

boolean result = MeaPushProvisioning.SamsungPay.isDefaultPaymentApplication(getContext());

Set Samsung Pay as default NFC payment app:

MeaPushProvisioning.SamsungPay.setAsDefaultPaymentApplication(getActivity(), SET_DEFAULT_PAYMENTS_REQUEST_CODE);

Getting Registered Tokens from Samsung Pay Wallet

There might be some use cases when Issuer app needs to get all registered tokens from Samsung Pay wallet, for example, yellow path use case. Method MeaPushProvisioning.SamsungPay.getRegisteredTokens(...) returns list of Card items related to the active wallet.

MeaPushProvisioning.SamsungPay.getRegisteredTokens(new SamsungPayRegisteredTokensListener() {
    @Override
    public void onSuccess(@NonNull List<Card> tokenList) {
        ...
    }

    @Override
    public void onFailure(@NonNull MppError error) {
        ...
    }
});

Debug and Release mode

Samsung Pay supports both debug and release modes. More details available in the Samsung Pay SDK documentation

Using Tokenization Data with Opaque Payment Card (OPC) for Samsung Pay

By directly using Tokenization Data developers can implement push provisioning flow using Samsung Pay Push Provisioning API, which allows developers to have more control over implementation, however requires more effort. MPP SDK provides opaque payment card (OPC) with MeaPushProvisioning.getSamsungPayTokenizationData(...) method.

MeaPushProvisioning.getSamsungPayTokenizationData(cardParams, "wallet-id-12345", "device-id-12345", this, new MppGetOemTokenizationDataListener() {
    @Override
    public void onSuccess(String opaquePaymentCard, String lastFourDigits, MppPaymentNetwork paymentNetwork) {
        ...
    }

    @Override
    public void onFailure(MppError mppError) {
        ...
    }
});

or

MppGetOemTokenizationDataResponseData responseData = MeaPushProvisioning.getSamsungPayTokenizationData(cardParams, "wallet-id-12345", "device-id-12345", this);

String opaquePaymentCard = responseData.getOpaquePaymentCard();
String lastFourDigits = responseData.getLastFourDigits();
MppPaymentNetwork paymentNetwork = responseData.getPaymentNetwork();

Use OPC data for Samsung Pay Push Provisioning API implementation:

• Samsung Pay SDK Programming Guide
• Samsung Pay Push Provisioning Use Case
• Samsung Pay Push Provisioning and open Favorite Cards API flow

App-to-App Verification with Activation Code

TSP Settings

Issuer's app can provide app-to-app verification as an option for completing a yellow path ID&V challenge when provisioning a card. App-to-app verification is configured through TSP.

Issuers must provide the following parameters to TSP to enable app-to-app verification. Samsung Pay receives these parameters from the TSP during the tokenization process and passes them to issuer App by launching it via startActivityForResult(intent, requestCode):

Parameter	Example	Description
Package name	com.example.bank	The package name (applicationId) identifies the issuer mobile app that Samsung Pay should call during when invoking the Intent to start the app to app flow. If the app is not installed on the cardholder's mobile device, the user will be prompted to install it from the Play Store.
Action	com.example.bank.action.APP_TO_APP	When calling your App, we create an explicit Intent. The action must be provided in it's fully qualified form, including the package name. Also, the action must be specific for use in token activation. Action name varies by TSP.
Intent.EXTRA_TEXT		As received from TSP server. For Mastercard, this is a Base64 encoded JSON object consisting of elements paymentAppProviderId, paymentAppInstanceId, tokenUniqueReference, accountPanSuffix, accountExpiry. For Visa, this will be an encrypted JSON payload consisting of PAN ID, TR ID, Token Reference ID, Last 4 of PAN, Device ID and Wallet Account ID.

info

Issuer should refer to specifications from Payment Networks for accurate details of data elements, encryption and other implementation requirements.

When user selects app-to-app verification, Samsung Pay invokes the issuer app for user's identity verification. Once the user has been verified, the issuer app passes control back to Samsung Pay to complete the provisioning flow.

App Implementation

Issuer's app must do the following to provide app-to-app verification functionality:

1. Receive Android Intent from Samsung Pay

When a user selects to verify their identity using the Issuer's App, Samsung Pay calls issuer's app using the package name, action and EXTRA_TEXT configured and provided through TSP. App manifest should be updated to be able to receive the Intent.

<activity android:name="AppToAppActivity">
  <!-- Activity that handles APP_TO_APP actions -->
  <intent-filter>
    <action android:name="com.example.bank.action.APP_TO_APP"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

info

App-to-app verification action name varies by TSP. Consult TSP technical documentation to determine what action name should be used.

2. Authenticate the cardholder

Use the standard issuer's app authentication to verify the user.

3. Get activation code

Application should determine the token state, method MeaPushProvisioning.SamsungPay.getRegisteredTokens(...) can be used or use data from the EXTRA_TEXT in the received Intent.

Use specific MppCardDataParameters and MeaPushProvisioning.SamsungPay.getActivationCode(MppCardDataParameters, Context, MppActivationCodeListener) method to get activation code to complete the provisioning flow. Received activation code should be used in the next step.

4. Return the user to Samsung Pay

User should be returned to Samsung Pay with an activation code:

    MeaPushProvisioning.SamsungPay.activate(activity, activationCode);

On failure, decline activation with ActivationResult:

    MeaPushProvisioning.SamsungPay.declineActivation(currentActivity, ActivationResult.DECLINE);

Debugging

Use dependency with -debug suffix to enable MeaPushProvisioning debugging and logging. See Gradle Configuration.