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) {
        ...
    }
});

Continuing Yellow Path Through Push Provisioning

Issuer app should allow users to continue yellow path through push provisioning.

Issuer app should get the token of the selected card and check the token state. After finding card with MeaPushProvisioning.SamsungPay.checkWalletForCardToken(MppCardDataParameters cardData, SamsungPayTokenListener listener) in Samsung Pay wallet, check the state of the token. If token state matches TOKEN_STATE_PENDING_PROVISION, card push provisioning has entered yellow path and requires additional user authentication. Once matching SamsungPayTokenInfo is available, use one of the following options to activate a token in yellow path:

• Pass the pending token's tokenId into the verifyCardIdv(...) method to continue provisioning.
• Remotely activate the token through a server-side activation call.

Using VerifyCardIdv

Show "Add to Samsung Pay" button, obtain Activation Code and call MeaPushProvisioning.SamsungPay.verifyCardIdv(...) to continue push provisioning, when the button is tapped.

MeaPushProvisioning.SamsungPay.checkWalletForCardToken(cardDataParameters, new SamsungPayTokenListener() {
    @Override
    public void onSuccess(@NonNull SamsungPayTokenInfo samsungPayTokenInfo) {
        Log.d(TAG, "SamsungPay.checkWalletForCardToken() success " + samsungPayTokenInfo);
        if (samsungPayTokenInfo.getTokenState() == TOKEN_STATE_PENDING_PROVISION) {
            // Card token requires additional user authentication for yellow path, show Add to Samsung Pay button.
            // When tapping button, call one of the activation options:
            // - MeaPushProvisioning.SamsungPay.activate(tokenId, paymentNetwork)
            // - MeaPushProvisioning.SamsungPay.verifyCardIdv(samsungPayTokenInfo.getTokenId(), activationCode, ...)
        }
        else {
            // Token already exists in Samsung Pay Wallet and no action required from Issuer app, hide Add to Google Pay button.
        }
    }
    @Override
    public void onFailure(@NonNull MppError mppError) {
        // Card token not found in Samsung Pay Wallet, show Add to Samsung Pay button.
        // When tapping button, call MeaPushProvisioning.SamsungPay.pushCard(...).
    }
});

Get activation code

Use specific MppCardDataParameters and MeaPushProvisioning.SamsungPay.getActivationCode(MppCardDataParameters, Context, MppActivationCodeListener) method to get activation code to complete the provisioning flow.

Using verifyCardIdv

Activate card with verifyCardIdv(...) method using samsungPayTokenInfo.getTokenId() and activation code obtained in previous step:

MeaPushProvisioning.SamsungPay.verifyCardIdv(samsungPayTokenInfo.getTokenId(), activationCode, new Bundle(), new MppListener() {
    @Override
    public void onSuccess() {
        // Card successfully activated
    }

    @Override
    public void onFailure(@NonNull MppError mppError) {
        // Activation failed
    }
});

Using Server-side Activation

// When Add to Samsung Pay button tapped.
MeaPushProvisioning.SamsungPay.activate(card, paymentNetwork, new MppActivateListener() {
    @Override
    public void onSuccess() {
        ...
    }

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

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

Issuers can offer app-to-app verification as an option for completing a yellow path ID&V challenge when provisioning a token. App-to-app verification is configured through TSP.

When user selects a card for activation with app-to-app verification, Samsung Wallet invokes the issuer app by calling the Android Activity specified by the issuer through TSP configuration. Once the user has verified their identity, the issuer app passes control back to Samsung Wallet to finish the provisioning flow.

Issuers can implement App-to-App Verification using one of the two methods:

• Obtaining activation code and passing to Samsung Wallet
• Server-side activation

TSP Settings

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 with 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.

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. Validate calling Activity

Upon receiving the Intent, use Activity.getCallingPackage() to validate that the calling Activity is actually Samsung Pay:

// Validate caller is Samsung Pay
if ("com.samsung.android.spay".equals(getCallingPackage())) {
    // Proceed with token activation
} else {
    // Abort token activation
}

3. Authenticate the cardholder

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

4. Activation

Application should determine the token state that indicates required verification, use method MeaPushProvisioning.SamsungPay.getRegisteredTokens(...) or MeaPushProvisioning.SamsungPay.getCard(Intent, listener) for the received Intent, which extracts token data from EXTRA_TEXT.

4.1. Activation Code

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.2. Server-side Activation

This method allows to activate the token using TSP APIs.

Use method MeaPushProvisioning.SamsungPay.activate(tokenUniqueReference, paymentNetwork) to activate the token.

5. Return the user to Samsung Pay

User should be returned to Samsung Wallet with activate(Activity, activationCode) method. Use activationCode for Activation Code method or method without activationCode argument for server-side activation.

MeaPushProvisioning.SamsungPay.activate(activity, activationCode);

Decline activation with ActivationResult on failure:

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

Debugging

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