Samsung Pay Integration Guide

This guide walks you through integrating Samsung Pay payments into your Flutter application using the Moyasar Flutter SDK. Samsung Pay support was added in moyasar v3.0.0 and enables users to pay securely using their Samsung Wallet on supported Samsung Android devices.

Prerequisites

Before you begin, ensure you have:

1. Moyasar account — Sign up if you haven't already
2. Publishable API key — Get your API keys
3. Samsung Developer Account — Create and configure your Samsung Pay service
4. Moyasar Flutter SDK — v3.0.0 or later (Samsung Pay was added in v3.0.0)
5. Samsung Android device — Samsung Pay works only on Samsung devices (emulators and non-Samsung devices are not supported)

Samsung Pay Setup

Before integrating in your app, complete the Samsung Pay setup:

1. Create a Samsung Developer Account and apply for Samsung Pay service
2. Generate and download the CSR from Moyasar Dashboard → Settings → Samsung Certificate → Request CSR
3. Create an InApp Online Payment service in Samsung Pay Service Management
4. Register your Android app with the exact package name you will publish under
5. Note your Service ID — you will need it for SamsungPayConfig

tip

Once you complete integration and perform test payments, your Service ID needs to be approved by Samsung Pay. Contact Moyasar to assist with activation.

Installation

Samsung Pay is available in moyasar v3.0.0 and later. Add the package to your pubspec.yaml:

dependencies:
  moyasar: ^3.0.0 # Samsung Pay requires v3.0.0 or later

Then run:

flutter pub get

Android Configuration

Required for Samsung Pay

Both steps below are required for Samsung Pay to work on Android. Without them, the Samsung Pay button will not appear or the payment flow will fail.

1. Set Minimum SDK Version

The Moyasar Flutter SDK depends on the pay package, which requires minSdkVersion 21 or higher. In android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21
    }
}

2. Add Samsung Pay Meta-Data

The Samsung Pay SDK requires the spay_sdk_api_level meta-data. Add it inside the <application> tag in android/app/src/main/AndroidManifest.xml:

<application
    android:label="your_app_name"
    android:icon="@mipmap/ic_launcher">

    <!-- Samsung Pay SDK configuration -->
    <meta-data
        android:name="spay_sdk_api_level"
        android:value="2.22" />

    <!-- ... other configuration ... -->
</application>

note

The android:value should match the Samsung Pay SDK API level. Samsung recommends 2.22 for the latest APIs. For Russia, use 2.17. See Samsung Pay SDK Overview for details.

Implementation

1. Configure SamsungPayConfig

Add SamsungPayConfig to your PaymentConfig:

import 'package:flutter/material.dart';
import 'package:moyasar/moyasar.dart';

final paymentConfig = PaymentConfig(
  publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY',
  amount: 25758, // SAR 257.58 (amount in minor unit: halalas)
  description: 'Order #1324',
  metadata: {'size': '250g'},
  samsungPay: SamsungPayConfig(
    serviceId: 'YOUR_SAMSUNG_SERVICE_ID',
    merchantName: 'YOUR_STORE_NAME',
    manual: false,
  ),
);

Parameter	Description
serviceId	Your Samsung Pay Service ID from the Samsung Developer Portal
merchantName	Display name shown to the user during payment
orderNumber	Optional. Unique alphanumeric transaction ID (max 36 chars). If omitted, SDK generates one. Required for refunds and Visa payments.
manual	Set to true for manual payment capture (authorize without charging)

2. Add the SamsungPay Widget

Use the built-in SamsungPay widget to display the Samsung Pay button:

class PaymentMethods extends StatelessWidget {
  PaymentMethods({super.key});

  final paymentConfig = PaymentConfig(
    publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY',
    amount: 25758,
    description: 'Order #1324',
    metadata: {'size': '250g'},
    samsungPay: SamsungPayConfig(
      serviceId: 'YOUR_SAMSUNG_SERVICE_ID',
      merchantName: 'YOUR_STORE_NAME',
      manual: false,
    ),
  );

  void onPaymentResult(result) {
    if (result is PaymentResponse) {
      switch (result.status) {
        case PaymentStatus.paid:
          // Payment successful — verify on your backend
          break;
        case PaymentStatus.failed:
          // Payment failed
          break;
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        SamsungPay(
          config: paymentConfig,
          onPaymentResult: onPaymentResult,
        ),
        const Text("or"),
        CreditCard(
          config: paymentConfig,
          onPaymentResult: onPaymentResult,
        ),
      ],
    );
  }
}

info

Always verify the payment on your backend using the Fetch Payment API before fulfilling the order. Never rely solely on the client-side result.

Testing

Test Environment

1. Use sandbox API keys (pk_test_...) for testing
2. Test on a real Samsung Android device — emulators and simulators do not support Samsung Pay
3. Add a real card to Samsung Wallet on your test device

Test Amounts

Samsung Pay testing uses amount-based simulation. Different amounts return different results:

Amount (Minor Unit)	Amount (SAR)	Status	Response
20000 to 30000	200.00 to 300.00	paid	APPROVED
100000 to 110000	1000.00 to 1100.00	failed	UNSPECIFIED FAILURE
110100 to 120000	1101.00 to 1200.00	failed	INSUFFICIENT FUNDS
120100 to 130000	1201.00 to 1300.00	failed	DECLINED: LOST CARD
130100 to 140000	1301.00 to 1400.00	failed	DECLINED
140100 to 150000	1401.00 to 1500.00	failed	DECLINED: EXPIRED CARD

See the full Samsung Pay Testing guide for all test amounts.

tip

Use amounts between 20000–30000 (SAR 200–300) to simulate successful payments in the sandbox.

Running the Example App

The moyasar-flutter example app uses product flavors:

• Apple Pay / default: flutter run --flavor default_
• Samsung Pay: flutter run --flavor spay

See the example CONFIGURATION_GUIDE for details.

Production Deployment

Before going live:

1. Replace test API keys with live keys (pk_live_...)
2. Ensure your package name matches the one registered in Samsung Pay
3. Complete Samsung Pay service approval with Samsung
4. Verify payment status on your backend for every transaction
5. Test the full flow on a production Samsung device

Troubleshooting

Issue	Solution
Samsung Pay button not showing	Ensure you're running on a Samsung device with Samsung Wallet installed and configured
"Service ID invalid"	Verify your Service ID in the Samsung Developer Portal and that your app's package name is registered
Payment fails immediately	Check that you're using the correct API key (test vs live) and that the amount is in the minor unit (halalas for SAR)
Build fails on Android	Ensure minSdkVersion is at least 21 and spay_sdk_api_level meta-data is present in AndroidManifest
Samsung Pay not available	Ensure you are using moyasar v3.0.0 or later. Samsung Pay was not supported in earlier versions.

Support

For integration help or Samsung Pay activation:

• Moyasar Support
• moyasar-flutter GitHub