Samsung Pay

Samsung Pay is easy to set up and gives your customers a simple and secure way to pay using their Samsung devices.
This guide explains how to process Samsung Pay payments with our SDK.

Requirements

A Mobile SDK Integration. (Ready-to-Use UI or SDK & Your Own UI)
An approved Samsung Account with Service and App configured.
SamsungPaySDK jar file for the correct region. To download the Samsung SDK, go here
A Samsung Device.

In order to use Samsung Pay, you will need to create keys and a CSR (certificate signing request). Here are the steps:

In the Till Payments Host, navigate to Administration -> Mobile Payment, select Generate keys and download CSR.
In the Samsung Pay Developer Center, choose Create New Service. Upload the CSR from the previous step.

Configuration

Add SamsungPaySDK jar.

Drag and drop SamsungPaySDK_2.18.00.jar to the "libs" folder. Update implementation in the build.gradle file. Add ".jar" alongside with the ".aar":

implementation fileTree(include: ["*.aar", "*.jar"], dir: "libs")

Open the AndroidManifest.xml file of your application and add the following into the application tag:

<meta-data
    android:name="debug_mode"
    android:value="Y" />
<meta-data
    android:name="spay_debug_api_key"
    android:value="debug_api_key" />
<meta-data
    android:name="spay_sdk_api_level"
    android:value="2.18" />

NOTE: change debug_mode to N, once review from Samsung is done and you are ready to go live.

Adding Samsung Pay to your app must be done in one of two ways, depending on whether you are using the Ready-to-Use UI or the SDK & Your Own UI. These two ways are covered in the sections below. Please follow the instructions relevant to the approach you have chosen.

Ready-to-Use UI

NOTE: It is important to add your applicationId to your App in the Samsung Pay Developers account. Otherwise Samsung Pay SDK won't return a payment token.

Add SAMSUNGPAY payment brand

Create the CheckoutSettings, and add the SAMSUNGPAY to the payment brands list:

Set<String> paymentBrands = new HashSet<String>();
paymentBrands.add("SAMSUNGPAY");

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, Connect.ProviderMode.TEST);

val paymentBrands = hashSetOf("SAMSUNGPAY") 
 
val checkoutSettings = CheckoutSettings(checkoutId, paymentBrands, Connect.ProviderMode.TEST)

Create SamsungPayConfig

Create SamsungPayConfig to configure Samsung Pay widget. It requires serviceId and CustomSheetPaymentInfo.

private SamsungPayConfig getSamsungPayConfig() {
    return new SamsungPayConfig(
        "serviceId",
        getCustomPaymentSheetInfo());
}

private CustomSheetPaymentInfo getCustomPaymentSheetInfo() {
    return new CustomSheetPaymentInfo.Builder()
        .setMerchantName("Sample merchant")
        .setCustomSheet(getCustomSheet(getTransactionAmount(),
            application.getCurrency().name()))
        .build();
}

private CustomSheet getCustomSheet(double amount, String currencyCode) {
    AmountBoxControl amountBoxControl = new AmountBoxControl("amountControlId", currencyCode);
    amountBoxControl.setAmountTotal(amount, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);

    CustomSheet customSheet = new CustomSheet();
    customSheet.addControl(amountBoxControl);

    return customSheet;
}

private fun getSamsungPayConfig(): SamsungPayConfig? {
    return SamsungPayConfig(
        "serviceId",
        getCustomPaymentSheetInfo())
}

private fun getCustomPaymentSheetInfo(): CustomSheetPaymentInfo? {
    return Builder()
        .setMerchantName("Sample merchant")
        .setCustomSheet(getCustomSheet(getTransactionAmount(),
            application.getCurrency().name()))
         .build()
}

private fun getCustomSheet(amount: Double, currencyCode: String): CustomSheet? {
    val amountBoxControl = AmountBoxControl("amountControlId", currencyCode)
    amountBoxControl.setAmountTotal(amount, AmountConstants.FORMAT_TOTAL_PRICE_ONLY)
    val customSheet = CustomSheet()
    customSheet.addControl(amountBoxControl)
    return customSheet
}

Set it to the CheckoutSettings.

checkoutSettings.setSamsungPayConfig(getSamsungPayConfig());

checkoutSettings.samsungPayConfig = getSamsungPayConfig()

Handle the card info update event

Samsung Pay provides the card info update event called when shopper changes card in Samsung Pay. Newly selected cardInfo is passed so the custom sheet can be updated accordingly. To handle this event create SamsungPayConfig.CardInfoUpdateListener and set it to the SamsungPayConfig.

public class SamsungPayCardInfoUpdateListener
        implements SamsungPayConfig.CardInfoUpdateListener {

    public SamsungPayCardInfoUpdateListener() {
        // do nothing
    }

    public SamsungPayCardInfoUpdateListener(@NonNull Parcel in) {
        // do nothing
    }

    @Override
    public void onCardInfoUpdated(@NonNull CardInfo selectedCardInfo,
                                  @NonNull CustomSheet customSheet) {
        // update custom sheet using selected card info
    }

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(@NonNull Parcel parcel,
                              int flags) {
        // do nothing
    }

    public static final Creator CREATOR
            = new Creator<SamsungPayCardInfoUpdateListener>() {
        @Override
        public SamsungPayCardInfoUpdateListener createFromParcel(Parcel in) {
            return new SamsungPayCardInfoUpdateListener(in);
        }

        @Override
        public SamsungPayCardInfoUpdateListener[] newArray(int size) {
            return new SamsungPayCardInfoUpdateListener[size];
        }
    };
}

class SamsungPayCardInfoUpdateListener() : SamsungPayConfig.CardInfoUpdateListener {

    constructor(parcel: Parcel) : this()

    override fun onCardInfoUpdated(selectedCardInfo: CardInfo,
                                   customSheet: CustomSheet) {
        // update custom sheet using selected card info
    }

    override fun writeToParcel(parcel: Parcel, flags: Int) {
        // do nothing
    }

    override fun describeContents(): Int {
        return 0
    }

    companion object CREATOR : Parcelable.Creator {
        override fun createFromParcel(parcel: Parcel): SamsungPayCardInfoUpdateListener {
            return SamsungPayCardInfoUpdateListener(parcel)
        }

        override fun newArray(size: Int): Array {
            return arrayOfNulls(size)
        }
    }
}

samsungPayConfig.setCardInfoUpdateListener(new SamsungPayCardInfoUpdateListener());

samsungPayConfig.cardInfoUpdateListener = SamsungPayCardInfoUpdateListener()

NOTE: If total amount was changed, use the before submit callback of the CheckoutActivity to send the checkout id update request with new amount. This request must be done server-to-server.

Handle the CustomSheetPaymentInfo before payment

The CheckoutActivity may send the callback when shopper submits the payment, see Receiving callbacks during checkout process. This callback can be used to check CustomSheetPaymentInfo and make a checkout update if required.

public class CheckoutBroadcastReceiver 
        extends BroadcastReceiver {

    @Override
    public void onReceive(@NonNull Context context, 
                          @NonNull Intent intent) {
        String action = intent.getAction();

        if (CheckoutActivity.ACTION_ON_BEFORE_SUBMIT.equals(action)) {
            CustomSheetPaymentInfo customSheetPaymentInfo = intent.getParcelableExtra(
                    CheckoutActivity.EXTRA_SAMSUNG_PAY_PAYMENT_DATA);

            // handle Samsung Pay custom sheet payment info
        }
    }
}

class BroadcastReceiver : BroadcastReceiver() { 
     
    override fun onReceive(context: Context, intent: Intent?) { 
        val action = intent?.action 
         
        if (CheckoutActivity.ACTION_ON_BEFORE_SUBMIT == action) { 
            val customSheetPaymentInfo: CustomSheetPaymentInfo = intent.getParcelableExtra(
                    CheckoutActivity.EXTRA_SAMSUNG_PAY_PAYMENT_DATA);

            // handle Samsung Pay custom sheet payment info
        } 
    } 
}

SDK & Your Own UI

Follow the Samsung Pay SDK Documentation to obtain the tokenized payment information necessary to make a transaction (In-App Payment).

Once you have the tokenized payment information, create SamsungPayPaymentParams and submit the transaction.

PaymentParams paymentParams = new SamsungPayPaymentParams(checkoutId, paymentCredential);
paymentParams.setShopperResultUrl("companyname://result");

try {
    OppPaymentProvider paymentProvider = new OppPaymentProvider(context, providerMode);
    paymentProvider.submitTransaction(new Transaction(paymentParams), transactionListener);
} catch (PaymentException e) {
    // handle payment exception
}

val paymentParams = SamsungPayPaymentParams(checkoutId, paymentCredential)
paymentParams.shopperResultUrl = "companyname://result"

try { 
     val paymentProvider = OppPaymentProvider(context, providerMode)
     paymentProvider.submitTransaction(Transaction(paymentParams), transactionListener) 
} catch (e: PaymentException) { 
     // handle payment exception
}