3.2 Samsung Pay SDK Flutter Plugin

3.2.1 Flutter Plugin Overview

The Samsung Pay SDK Flutter Plugin allows developers to integrate select features of Samsung Wallet into Flutter-based Android apps running on Samsung devices. It acts as a bridge between the Flutter environment and the native Samsung Pay SDK, enabling secure and seamless payments through Samsung Pay.

Purpose

The primary aim of this plugin is to bring Samsung Pay SDK functionality into the Flutter ecosystem—making it easier for developers to integrate mobile wallet capabilities without deep native Android coding.

Supported Operations

The Samsung Pay SDK Flutter Plugin supports the following major operations:

• In-App Payment: Lets users pay for goods and services within a partner app using Samsung Wallet.
• Push Provisioning: Enables users to add bank cards directly to Samsung Wallet from the issuer’s app by providing required card details.

What’s Included in the Plugin Package

To support seamless integration, the Flutter plugin package typically includes:

• Samsung Pay SDK Flutter Plugin
  • Dart interface, platform channel code, and native Android SDK wrappers (Java/Kotlin).
  • Contains all classes, interfaces, and native libraries needed to communicate with Samsung Pay services.
• API Reference Documentation
  • Detailed descriptions of each supported API method and parameters.
  • Usage guidance for implementing features like getSamsungPayStatus(), activateSamsungPay(), and transaction callbacks.
• Sample Merchant & Issuer Apps
  • Complete working examples of how to:
    • Accept in-app payments
    • Push provision a card into Samsung Wallet
    • Handle callback responses and errors
  • Demonstrates full implementation using Flutter UI and platform logic.

Benefits of Using the Flutter Plugin

• Cross-platform development with native payment features
• Faster time to market by avoiding full native SDK integration
• Pre-built sample apps and APIs to accelerate onboarding
• Seamless integration with Samsung’s trusted payment environment
  
  

3.2.2 Samsung Pay SDK Flutter Plugin Architecture

The following diagram illustrates the high-level architecture and core interactions between the Samsung Pay SDK Flutter Plugin and a partner app. At this level, the plugin enables partner apps to leverage Samsung Pay for key operations such as push provisioning (for issuers) and in-app payments (for merchants).

Key components and roles

• Partner App - A Flutter-based app developed by a merchant or issuer.
  It integrates Samsung Pay features to support:
  • In-app or online payments (merchants)
  • Push provisioning and management (issuers)
• Samsung Pay SDK Flutter Plugin - The plugin layer embedded in the partner app. It enables direct communication between the Flutter app and Samsung Pay services on the device by bridging native SDK APIs.
• Samsung Pay App - The native Samsung Pay (Samsung Wallet) application on the user’s device. It securely handles payment authorization, tokenization, card management, and transaction UI.
• Financial Network - The back-end payment ecosystem, including:
  • Payment gateways (PGs)
  • Acquirers and issuers
  • Card associations (e.g., Visa, Mastercard)
    These entities work together to process transactions initiated through Samsung Pay under merchant agreements.
    
    

3.2.3 Setting up Flutter Plugin Environment

Establishing a stable and well-configured development environment is essential for the successful integration of the Samsung Pay SDK Flutter Plugin into your partner app. The following prerequisites and recommendations will help ensure a smooth setup and implementation.

Prerequisites & Requirements

• Platform Compatibility
  Ensure your app is targeting Android devices that support Samsung Pay. For detailed Android system requirements, refer to the [Samsung Pay Android SDK Overview].
• Service Registration
  To use the plugin, merchants and issuers must first register a service through the Samsung Pay Developer Portal. This includes obtaining a valid Service ID (SID) and Service Type required for integration.
  Refer to the [Service Registration Guide] for step-by-step instructions.
• Download the Flutter Plugin
  Obtain the official Samsung Pay SDK Flutter Plugin package, which includes:
  • Plugin libraries and dependencies
  • API documentation
  • Sample Flutter apps for merchant and issuer use cases

The plugin has the following directory structure:

Folder	Contents
Docs	API reference documentation
Libs	samsungpaysdkflutter_v1.01.00 flutter plugin – contains the Samsung Pay APIs to be used by your partner app
Samples	Sample apps

3.2 4 Integrate Samsung Pay SDK Flutter Plugin

Be sure to do the following before attempting to use the Plugin:

1. If not already part of your environment, download and install an IDE. Android Studio is recommended.
2. Download the Samsung Pay SDK Flutter Plugin

Configure your IDE to integrate the Samsung Pay SDK Flutter Plugin with your partner app.

• Go to pubspec.yaml and enter the following dependency:

dependencies:

samsung_pay_sdk_flutter: 
path: plugin_directory_path\

[NOTE] If your plugin path is C:\Users\USERNAME\Downloads, the dependency will be like below:

dependencies:

samsung_pay_sdk_flutter: 
path: C:\Users\USERNAME\Downloads\

For Android ProGuard rules and DexGuard, please check the Android SDK Overview.

3.2.5 Common Flow

Once the setup is complete, you're ready to start integrating Samsung Pay features into your partner app using the Samsung Pay SDK Flutter Plugin. The plugin provides APIs for the following core functionalities:

Supported Operations via APIs:

• Check Samsung Wallet Status
• Activate the Samsung Wallet App
• Update the Samsung Wallet App

Checking Samsung Wallet Status

The first step is to create a SamsungPaySdkFlutter instance. This instance checks whether Samsung Wallet is supported and ready to use on the user’s device. Based on the result, your app will determine whether to display the Samsung Pay button (for both merchant payments and issuer Push provisioning).

String serviceId; 
Map<String,dynamic> data; 
static final samsungPaySdkFlutterPlugin = SamsungPaySdkFlutter(PartnerInfo(serviceId: 'partner_app_service_id', data: {SpaySdk.PARTNER_SERVICE_TYPE:ServiceType.APP2APP.name.toString()}));

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 Flutter Plugin.

Future<void> getSamsungPayStatus(StatusListener? statusListener)

The result is delivered to StatusListener and provides onSucccess and onFail events. Check the Android SDK Common Flow for more details.

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

MyHomePage.samsungPaySdkFlutterPlugin.getSamsungPayStatus(StatusListener(onSuccess:(status, bundle) async { 
showStatus(status, bundle);
}, onFail:(errorCode, bundle){
showError(errorCode, bundle);
} 
));

Activating the Samsung Wallet App

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

Future<void> activateSamsungPay()

activateSamsungPay() is called to activate the Samsung Wallet app on the same device on which the partner app is running. First, the partner app must check the Samsung Wallet status with a getSamsungPayStatus() call. 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

samsungPaySdkFlutterPlugin.activateSamsungPay();

Updating the Samsung Wallet App

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

Future<void> 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 Wallet 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 Wallet update page.

The following code sample reflects how to update Samsung Wallet:

samsungPaySdkFlutterPlugin.goToUpdatePage();

3.2.6 In-app (Online)

Merchant applications can initiate secure In-App payments by interacting with the Samsung Pay SDK Flutter Plugin. This process allows apps to display a custom payment sheet, retrieve card information, and handle payment requests smoothly within the app.

The following functionalities are ready to perform a variety of payment operations:

Checking registered/enrolled card information

Before displaying the Samsung Pay button, a partner app can query card brand information for the user’s currently enrolled payment cards in Samsung Wallet to determine if payment is supported with the enrolled card.

To query the card brand, use the requestCardInfo() API method of the SamsungPaySdkFlutter class. The merchant app does not need to set a value for it now. However, before calling this method, CardInfoListener must be registered so its listener can provide onResult and onFailure events:

The following snippet shows how to retrieve the list of supported card brands from Samsung Wallet:

samsungPaySdkFlutterPlugin.requestCardInfo(cardInfoListener){onResult:(paymentCardInfo) 

    showCardList(paymentCardInfo); 
    
    }, onFailure:(errorCode, bundle){ 
    
    showError(errorCode, bundle); 
        
    } 
    ));

Creating a Transaction Request

Upon successful initialization of the SamsungPaySdkFlutter class, the merchant app needs to create a transaction request with payment information.

Using the custom payment sheet

To initiate a payment transaction with Samsung Wallet’s custom payment sheet, your merchant app must populate the following mandatory fields in CustomSheetPaymentInfo:

• Merchant Name - as it will appear in Samsung Wallet’s payment sheet, as well as the user's card account statement.
• CustomSheet - is called when the user changes card on the custom payment sheet in Samsung Wallet.

Optionally, the following fields can be added to the payment information:

• Merchant ID - can be used for the merchant’s own designated purpose at its discretion unless the merchant uses an indirect PG like Stripe or Braintree. If an indirect PG is used, this field must be set to the merchant’s Payment Gateway ID fetched from the Samsung Pay Developers portal.
• Order Number - usually created by the merchant app via interaction with a PG. This number is required for refunds and chargebacks. In the case of Visa cards, the value is mandatory. The allowed characters are [A-Z][a-z][0-9,-] and the length of the value can be up to 36 characters.
• Address - the user’s billing and/or shipping address.
• Allowed Card Brands - specifies card brands accepted by the merchant. If no brand is specified, all brands are accepted by default. If at least one brand is specified, all other card brands not specified are set to "card not supported’ on the payment sheet.

Here’s the 'CustomSheetPaymentInfo' structure:

    String? merchantId; 
    String merchantName; 
    String? orderNumber; 
    AddressInPaymentSheet? addressInPaymentSheet; 
    List<Brand>? allowedCardBrand; 
    PaymentCardInfo? cardInfo; 
    bool? isCardHolderNameRequired; 
    bool? isRecurring; 
    String? merchantCountryCode; 
    CustomSheet customSheet; 
    Map<String,dynamic>? extraPaymentInfo;

Your merchant app sends this CustomSheetPaymentInfo to Samsung Wallet via the applicable Samsung Pay SDK Flutter Plugin API methods. Upon successful user authentication in direct mode, Samsung Wallet returns the above "Payment Info" structure and a result string. The result string is forwarded to the PG by your merchant app to complete the transaction. It will vary based on the PG you’re using.

The following example demonstrates how to populate customSheet in the CustomSheetPaymentInfo class.

    List<Brand> brandList = [];
    brandList.add(Brand.VISA);
    brandList.add(Brand.MASTERCARD);
    brandList.add(Brand.AMERICANEXPRESS);


    CustomSheetPaymentInfo customSheetPaymentInfo= CustomSheetPaymentInfo(merchantName:"merchantName", customSheet: customSheet);
    customSheetPaymentInfo.setMerchantId("123456");
    customSheetPaymentInfo.setMerchantName("Sample Merchant");
    customSheetPaymentInfo.setAddressInPaymentSheet(AddressInPaymentSheet.NEED_BILLING_SEND_SHIPPING);
    customSheetPaymentInfo.setCardHolderNameEnabled(true);
    customSheetPaymentInfo.setRecrringEnabled(false);
    customSheetPaymentInfo.setCustomSheet(customSheet);
    customSheetPaymentInfo.allowedCardBrand = brandList;
  return customSheetPaymentInfo;

Requesting payment with a custom payment sheet

The startInAppPayWithCustomSheet() method of the SamsungPaySdkFlutter class is applied to request payment using a custom payment sheet in Samsung Wallet.

The two methods are defined as follows:

• startInAppPayWithCustomSheet() - initiates the payment request with a custom payment sheet. The payment sheet persists for 5 minutes after the API is called. If the time limit expires, the transaction fails.
• updateSheet() - updates the custom payment sheet if any values on the sheet are changed. As of API level 1.5, a merchant app can update the custom sheet with a custom error message. Refer to Updating sheet with custom error message.

When you call the startInAppPayWithCustomSheet() method, a custom payment sheet is displayed on the merchant app screen. From it, the user can select a registered card for payment and change the billing and shipping addresses, as necessary.

The result is delivered to CustomSheetTransactionInfoListener, which provides the following events:

• onSuccess() - called when Samsung Wallet confirms payment. It provides the CustomSheetPaymentInfo object and the paymentCredential JSON string.
• CustomSheetPaymentInfo is used for the current transaction. It contains amount, shippingAddress, merchantId, merchantName, orderNumber. API methods exclusively available in the onSuccess() callback comprise:
  • getPaymentCardLast4DPAN() – returns the last 4 digits of the user's digitized personal/primary identification number (DPAN)
  • getPaymentCardLast4FPAN() – returns the last 4 digits of the user's funding personal/primary identification number (FPAN)
  • getPaymentCardBrand() – returns the brand of the card used for the transaction
  • getPaymentCurrencyCode() – returns the ISO currency code in which the transaction is valued
  • getPaymentShippingAddress() – returns the shipping/delivery address for the transaction
  • getPaymentShippingMethod() – returns the shipping method for the transaction.

For PGs using the direct model (network tokens), the paymentCredential is a JSON object containing encrypted cryptogram which can be passed to the PG. PGs using the indirect model (gateway tokens) like Stripe, it is a JSON object containing reference (card reference – a token ID generated by the PG) and status (i.e., AUTHORIZED, PENDING, CHARGED, or REFUNDED). Refer to Payment credential sample for details.

• onCardInfoUpdated() - called when the user changes the payment card. In this callback, updateSheet() method must be called to update current payment sheet.
• onFailure() - called when the transaction fails, returns the error code and errorData bundle for the failure.

Here’s how to call the startInAppPayWithCustomSheet() method of the SamsungPaySdkFlutter class:

class CustomSheetTransactionInfoListener{
  Function(PaymentCardInfo paymentCardInfo, CustomSheet customSheet) onCardInfoUpdated;
  Function(CustomSheetPaymentInfo customSheetPaymentInfo, String paymentCredential,  Map<String, dynamic>? extraPaymentData) onSuccess;
  Function(String errorCode, Map<String, dynamic> bundle) onFail;
  CustomSheetTransactionInfoListener({required this.onCardInfoUpdated, required this.onSuccess, required this.onFail});
}

void onCardInfoUpdated(CardInfo selectedCardInfo, CustomSheet customSheet) {
    AmountBoxControl amountBoxControl =
        customSheet.getSheetControl(AMOUNT_CONTROL_ID) as AmountBoxControl;
    amountBoxControl.updateValue(PRODUCT_ITEM_ID, 1000);
    amountBoxControl.updateValue(PRODUCT_TAX_ID, 50);
    amountBoxControl.updateValue(PRODUCT_SHIPPING_ID, 10);
    amountBoxControl.updateValue(PRODUCT_FUEL_ID, 0, "Pending");
    amountBoxControl.setAmountTotal(1060, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);
    customSheet.updateControl(amountBoxControl);
  }
}

void startInAppPayWithCustomSheet(CustomSheetPaymentInfo customSheetPaymentInfo,CustomSheetTransactionInfoListener? customSheetTransactionInfoListener){
    try{
      methodChannelSamsungPaySdkFlutter?.startInAppPayWithCustomSheet(customSheetPaymentInfo, customSheetTransactionInfoListener);
    }on PlatformException catch(e){
      print(e);
    }
  }
override fun onSuccess(response: CustomSheetPaymentInfo, paymentCredential: String, extraPaymentData: Bundle){}
 override fun onFailure(errorCode: Int, errorData: Bundle?){}

3.2.7 Push Provisioning

The App-to-App service, also known as Push Provisioning, allows issuer apps to seamlessly add payment cards to the Samsung Wallet on a user’s Samsung device—directly from within the app—using the Samsung Pay SDK Flutter Plugin.

This integration enhances the user experience by eliminating the need to manually launch Samsung Wallet or scan physical cards.

Requesting Registered Card List in the Samsung Wallet

The getAllCards() method of the CardManager() class is used to request a list of all cards currently registered/enrolled in Samsung Wallet on the same device running the issuer’s app. To succeed, the issuer app must pass valid PartnerInfo to 'CardManager' for caller verification. 'cardFilter' narrows the card list returned by Samsung Wallet to the issuerName specified.

Please be noted that getSamsungPayStatus() must be called before getAllCards() . getAllCards() could not return a cards list when getSamsungPayStatus() responds with a code other than SPAY_READY().

As of API level (SDK version) 1.4, cardFilter retrieves this information from the Samsung Pay Developers portal. Certain issuers may need to register multiple ISSUER NAME(s) with the portal, depending on their app and/or the requirements of their token service provider (TSP). The getAllCards() parameter cardFilter matches the ISSUER NAME(s) specified with those registered in the portal. Only complete matches are returned.

This method is typically called when your partner app wants to check the card status. It does not need to be called every time the partner app resumes. Therefore, you should create the card list with the 'onCreate()' method, rather than the 'onResume()' method.

The result of a getAllCards() call is delivered to GetCardListener, which provides the following events:

• onSuccess() - called when the operation succeeds; provides the list of all filtered cards and their status. Card information includes cardId, cardStatus, and extra cardInfo data.
• onFail() - called when the operation fails.

Here’s an example of how to use the 'getAllCards()' API method in your issuer app.

 samsungPaySdkFlutterPlugin.getAllCards(GetCardListener(onSuccess:(list){
      showCardList(list);
    }, onFail:(errorCode, bundle){
      showError(errorCode, bundle);
    }));

Getting Wallet Information

The SamsungPay class provides the getWalletInfo() API method, which is called to request wallet information from the Samsung Wallet app prior to calling the addCard() API, when you want to avoid duplicate provisioning. Your issuer app uses this information to uniquely identify the user and the Samsung Wallet app on a particular device (wallet device management ID, device ID, and wallet user ID).

 void getWalletInfo(StatusListener? statusListener)

The following example demonstrates how to use it.

    String serviceId;
    SpaySdk.PARTNER_SERVICE_TYPE: ServiceType.APP2APP.name.toString()

    SamsungPaySdkFlutter(PartnerInfo(serviceId: "", data: {}));
    samsungPay=SamsungPay(context,partnerInfo)

    val keys = ArrayList<String>()
    keys.add(SamsungPay.WALLET_DM_ID)
    keys.add(SamsungPay.DEVICE_ID)
    keys.add(SamsungPay.WALLET_USER_ID)
samsungPaySdkFlutterPlugin.getWalletInfo(StatusListener(onSuccess: (status, bundle) async {
      val deviceId: String? = walletData.getString(SamsungPay.DEVICE_ID)
      val walletUserId: String? = walletData.getString(SamsungPay.WALLET_USER_ID)
    }, onFail: (errorCode, bundle) {

      Util.showError(context, errorCode, bundle);
    }));

Adding a Card to Samsung Wallet

Your issuer app calls the addCard() API method of CardManager to add a card to Samsung Wallet. By providing the required card details, your app can make it convenient and easy for users to add their bank-issued debit/credit cards to Samsung Wallet directly from your app without additional steps, like switching between apps.

For most issuers, getWalletInfo() suffices for requesting current wallet information. The response from Samsung Wallet tells the issuer app whether or not the user’s card has already been added to Samsung Wallet or is ineligible for provisioning. It is therefore recommended that you call getWalletInfo() before displaying the Add to Samsung Pay button. If the card is eligible, display the “add” button and, if the user taps it, call addCard().

The addCard() result is delivered to AddCardListener, which provides the following events:

onSuccess() - called when the operation succeeds; provides information and status regarding the added card.

onFail() - called when the operation fails; returns the error code and extra bundle data such as EXTRA_ERROR_REASON or EXTRA_REQUEST_ID (if provided).

onProgress() - called to indicate the current progress of the 'addCard()' operation; can be used to show a progress bar to the user in the issuer app. This callback is supported for TSM solution issuers in China and Spain.

Here’s an example of how to use the addCard() API method in your issuer app:

String cardType = WalletCard.CARD_TYPE_CREDIT_DEBIT;
String tokenProvider = AddCardInfo.PROVIDER_ABCD;
String testPayload = "TestPayloadCardInfoforFlutterPlugin";
Map<String, dynamic> cardDetail = {};

cardDetail[AddCardInfo.EXTRA_PROVISION_PAYLOAD] =  testPayload;

var addCardInfo = AddCardInfo(cardType, tokenProvider,cardDetail);

MyApp.samsungPaySdkFlutterPlugin.addCard(addCardInfo, AddCardListener(onSuccess: (status, card){

    print("Success : $status / Data : $card");

},onFail: (errorCode, bundle){

        Util.showError(context, errorCode, bundle);

print("Error : $errorCode / Data : $bundle");

    },ON-PROGRESS: (currentCount, totalCount, bundle){

print("currentCount : $currentCount / totalCount : $totalCount / Data : $bundle");

  }));

3.2.8 Sample Apps

Sample Applications

Sample apps with UX strategies are included here to aid you in understanding the SDK and implementing it in your application. Sample source code and APKs can be downloaded from Download section.

Sample merchant app

The sample merchant app shows you how to implement the payment sheet’s dynamic controls to leverage additional customer order and payment data and/or create a more custom UI look and feel.

The following payment sheet controls are available:

• AddressControl
• PlainTextControl
• AmountBoxControl
• SpinnerControl

Controls are applied to suit a particular purpose or need. Check this Android SDK Sample Merchant App for details.

Sample issuer app

The Samsung Pay SDK Flutter Plugin also provides a sample issuer app to showcase Samsung Pay SDK features.

For more information, refer to the Javadoc Samsung Pay SDK API reference and sample code.