Initiate Samsung Pay service

Once setup is complete, you’re ready to add the SDK code within your partner app for calling the SDK’s APIs and receiving callbacks.

API Common flow

When a partner app calls one of the SDK’s APIs, the following interaction flow is processed to check whether the caller is authenticated and authorized before responding to the request. The steps of the interaction are enumerated below.

1. The partner app calls an SDK API
2. The SDK checks the call’s validity
   
   - Is Samsung Pay installed on the device?
   
   - Is there any problem with the integrity of Samsung Pay on the device?
3. SDK calls the Samsung Wallet app using AIDL
4. Check the current status of the Samsung Wallet app
   
   - Is Samsung Pay provisioning complete?
   
   - Does Samsung Pay need a mandatory update?
   
   - Is the Samsung Pay SDK API level higher than the SDK API level in the partner app?
5. Request verification of partner app eligibility status from the Samsung Pay Server
6. Verify that the partner app matches the information registered in Samsung Pay Developers
7. Samsung Wallet app responds to the SDK request using AIDL
8. The SDK calls the callback function of the partner app.

---

Checking Samsung Pay status

The first step in implementing the Samsung Pay SDK within your partner app is to create the SamsungPay instance and check the Samsung Pay status on the device to determine its support for Samsung Pay (or lack thereof), and whether or not to display the Samsung Pay button to the user for selection as a payment option. The Samsung Pay button also lets issuer apps add a card to Samsung Pay. In both instances, the partner app must have valid PartnerInfo to pass to SamsungPay for caller verification.

To set its PartnerInfo, the partner app passes its serviceId (SID) and ServiceType, both of which are assigned by the Samsung Pay Developers portal when you create the service. Used for checking blocked list and version control between the Samsung Pay SDK and the Samsung Wallet app on the device, you must set the ServiceType in PartnerInfo to call other Samsung Pay APIs.

val serviceId = "partner_app_service_id"
val bundle = Bundle()
bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SamsungPay.ServiceType.INAPP_PAYMENT.toString())
val partnerInfo = PartnerInfo(serviceId, bundle)

After setting PartnerInfo, your partner app can now call getSamsungPayStatus(). This method of the SamsungPay class must be called before using any other feature in the Samsung Pay SDK.

fun getSamsungPayStatus(callback : StatusListener)

The result is delivered to StatusListener and provides the following events:

• onSuccess() ‒ Called when the requested operation is successful. It provides the status of the request, as well as extra bundle data related to the request.

• onFail() ‒ Called when the request operation fails. It returns the error code and extra bundle data related to the request.

The Samsung Pay status code returned is one of the following:

• SPAY_NOT_SUPPORTED - indicates Samsung Wallet is not supported on this device; typically returned if the device is incompatible with Samsung Pay or if the Samsung Wallet app is not installed.

• SPAY_NOT_READY - indicates Samsung Wallet is not completely activated; usually returned if the user did not complete a mandatory update or if the user has not signed in with a valid Samsung Account. In which case, the partner app can activate or update the Samsung Wallet app on the device according to the 'EXTRA_ERROR_REASON' bundle keys below.

  • ERROR_SPAY_SETUP_NOT_COMPLETE - tells the partner app to display a popup message asking if the user wishes to activate Samsung Pay. If the user agrees, the partner app calls activateSamsungPay() to activate the Samsung Wallet app.
  • ERROR_SPAY_APP_NEED_TO_UPDATE - tells the partner app to display a popup message asking if the user wishes to update Samsung Pay. If user agrees, the partner app calls goToUpdatePage() to open the app update page.

• ERROR_PARTNER_INFO_INVALID - indicates that Partner app information is invalid; typically the partner app is using a SDK version that is not allowed, an invalid service type, or the wrong API level.

  • ERROR_PARTNER_SDK_API_LEVEL - tells the partner app it is using the wrong API level. To resolve the error condition, the partner app must set a valid API level.
  • ERROR_PARTNER_SERVICE_TYPE - tells the partner app that it did not set a Service Type, or that the Service Type it did set is invalid. Service Type is set in PartnerInfo.

• SPAY_READY - indicates that Samsung Pay is activated and ready to use; typically returned after the user completes all mandatory updates and signs in.

Extra bundle data can have the following values:

• EXTRA_COUNTRY_CODE - for both onSuccess() and onFailure(), this is the current device’s country code (ISO 3166-1 alpha-2) set by Samsung Pay. If the partner app is not supported in this particular country, the partner app can decide not to display Samsung Pay button.

• EXTRA_ERROR_REASON - for onFailure(), this is the reason for failure set by Samsung Pay.

When the returned status code is SPAY_READY, the partner app can safely display the Samsung Pay button for user selection as a payment option, card provisioning, and so on.

The following sample code shows how to use the getSamsungPayStatus() API method:

val serviceId = "partner_app_service_id"
val bundle = Bundle()
bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SamsungPay.ServiceType.INAPP_PAYMENT.toString())
val partnerInfo = PartnerInfo(serviceId, bundle)
val samsungPay = SamsungPay(context, partnerInfo)
/*
 * Method to get the Samsung Pay status on the device.
 * Partner (Issuers, Merchants) applications must call this Method to
 * check the current status of Samsung Pay before doing any operation.
 */
samsungPay.getSamsungPayStatus(object : StatusListener {
    override fun onSuccess(status: Int, bundle: Bundle) {
        when (status) {
            SamsungPay.SPAY_NOT_SUPPORTED ->
                // Samsung Pay is not supported
                samsungPayButton.setVisibility(View.INVISIBLE)

            SamsungPay.SPAY_NOT_READY -> {
                // Activate Samsung Pay or update Samsung Pay, if needed
                samsungPayButton.setVisibility(View.INVISIBLE)
                val errorReason = bundle.getInt(SamsungPay.EXTRA_ERROR_REASON)
                if (errorReason == SamsungPay.ERROR_SETUP_NOT_COMPLETED) {
                    // Display an appropriate popup message to the user
                    samsungPay.activateSamsungPay()
                } else if (errorReason == SamsungPay.ERROR_SPAY_APP_NEED_TO_UPDATE) {
                    // Display an appropriate popup message to the user
                    samsungPay.goToUpdatePage()
                } else {
                    Toast.makeText(context, "error reason: $errorReason", Toast.LENGTH_LONG).show()
                }
            }

            SamsungPay.SPAY_READY ->
                // Samsung Pay is ready
                samsungPayButton.setVisibility(View.VISIBLE)

            else ->
                // Not expected result
                samsungPayButton.setVisibility(View.INVISIBLE)
        }
    }

    override fun onFail(errorCode: Int, bundle: Bundle) {
        samsungPayButton.setVisibility(View.INVISIBLE)
        Log.d(TAG, "checkSamsungPayStatus onFail() : $errorCode")
    }
})

---

Activating the Samsung Wallet App

The SamsungPay class provides the following API method to activate the Samsung Wallet app on a device:

fun activateSamsungPay()

activateSamsungPay() is called to activate the Samsung Wallet app on the same device on which the partner app is running. First, however, the partner app must check the Samsung Pay status with a getSamsungPayStatus() call (see section 4.2 above). If the status is SPAY_NOT_READY and EXTRA_ERROR_REASON is ERROR_SPAY_SETUP_NOT_COMPLETE, the partner app needs to display an appropriate message to user, then call activateSamsungPay() to launch the Samsung Wallet app so the user can sign in.

Here’s an example of how to code this:

val serviceId = "partner_app_service_id"
val bundle = Bundle()
bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SpaySdk.ServiceType.INAPP_PAYMENT.toString())
val partnerInfo = PartnerInfo(serviceId, bundle)
val samsungPay = SamsungPay(context, partnerInfo)
samsungPay.activateSamsungPay()

---

Updating the Samsung Wallet App

The SamsungPay class provides the following API method to update the Samsung Wallet app on the device:

fun goToUpdatePage()

goToUpdatePage() is called to update Samsung Wallet app on the same device on which the partner app is running.

As with all API calls, the partner app must first check the Samsung Pay status with getSamsungPayStatus(). If this returns SPAY_NOT_READY and EXTRA_ERROR_REASON is ERROR_SPAY_APP_NEED_TO_UPDATE, then the partner app needs to display an appropriate message to the user and call goToUpdatePage(), which launches the Samsung Pay update page.

The following code sample reflects how to update Samsung Pay:

val serviceId = "partner_app_service_id"
val bundle = Bundle()
bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SpaySdk.ServiceType.INAPP_PAYMENT.toString())
val partnerInfo = PartnerInfo(serviceId, bundle)
val samsungPay = SamsungPay(context, partnerInfo)
samsungPay.goToUpdatePage()

---