doc

Getting Started with the Flutter plug-in for Mobile Payments SDK

This guide walks you through the process of setting up a new Flutter project with Mobile Payments SDK. See the Flutter Mobile Payments SDK Technical Reference for more detailed information about types and methods.

Before you start

• You will need a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.
• Set-up your Flutter environment by following the official guide.

Step 1: Install Flutter plugin for Mobile Payments SDK

Install the Mobile Payments SDK package with pub:

flutter pub add mobile-payment-sdk-flutter

For iOS:

1. Make sure you run pod install in the ios folder of the sample application to install the SDK and all the dependencies.
2. Open your iOS project Runner.xcodeproj with Xcode.
3. Set the iOS Deployment Target to 12.0 or above.
4. Add an Mobile Payments SDK build phase:
   1. Open Runner.xcworkspace in Xcode.
   2. In the Build Phases tab for your application target, click the + button at the top of the pane.
   3. Select New Run Script Phase.
   4. Paste the following into the editor panel of the new run script:

      FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}"
      "${FRAMEWORKS}/SquareMobilePaymentsSDK.framework/setup"
      

For Android:

1. Modify your /android/build.gradle
   • Add squareSdkVersion = "2.0.1" inside the ext {...} block
   • Add maven { url 'https://sdk.squareup.com/public/android/' } inside the allprojects's repositories {...} block
2. Modify your /android/app/build.gradle
   • Add implementation("com.squareup.sdk:mobile-payments-sdk:$squareSdkVersion") inside the dependencies{...} block
3. Disable Proguard by adding the following to your /android/app/build.gradle:

android {
    buildTypes {
        release {
            minifyEnabled false
            shrinkResources false
        }
    }
}

You can also refer to MPSDK Android Quickstart's SDK installation section.

Step 2: Square Application ID and Access Token

1. Visit the Square Developer Console and sign in or create an account.
2. Create a new Square application.
3. Open the Credentials page and make note of your Application ID and Access token. Note at the top there's a switch to choose Sandbox or Production environment.
4. Open the Locations page, and make note of the Location ID of the location you'd like to use.

Step 3: Additional Platform Setup

1. For iOS: update your application delegate as follows:

import SquareMobilePaymentsSDK
// ...
override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    let applicationId = "REPLACE ME!"
      MobilePaymentsSDK.initialize(squareApplicationID: applicationId)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

1. For Android: update your MainApplication.kt file as follows:

import android.app.Application
import com.squareup.sdk.mobilepayments.MobilePaymentsSdk

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        MobilePaymentsSdk.initialize("Your Square Application ID", this)
    }
}

Step 4: Implement Authorization

To authorize the SDK, you'll need the Access token and Location ID noted before. Then, in your Flutter application:

import 'package:square_mobile_payments_sdk/square_mobile_payments_sdk.dart';
//...
final _squareMobilePaymentsSdkPlugin = SquareMobilePaymentsSdk();
try {
    response = await _squareMobilePaymentsSdkPlugin.authorize("accessToken", "locationId")
    print('Successful authorization: $response');
} catch (e) {
    print('Authorization error: $e');
}

You can use the getAuthorizedLocation() and getAuthorizationState() methods to retrieve the location and authorization status on any screen.

Finally, you can deauthorize a client by calling deauthorize().

Step 5: Show the settings screen

In order to pair a reader, you can show the settings screen, which allows reader pairing, checking reader status, and unpairing. To do this, simply call showSettings(), and to hide the settings page, the user can dismiss it by tapping on the close button. If you try to present settings while it's already being displayed, you will get an error, so make sure to use a try/catch block to handle this.

Step 6: Take a payment

To take a payment, you must pass it a PaymentParameters object, which includes payment-specific values such as amount, tip, location; and a PromptParameters, which includes the payment methods offered to the customer, and the display mode (which for now only supports the default mode of presenting over a given view). This will look like this:

import 'package:square_mobile_payments_sdk/square_mobile_payments_sdk.dart';
//...
final _squareMobilePaymentsSdkPlugin = SquareMobilePaymentsSdk();
try {
    String idempotencyKey = uuid.v4();
    Payment payment = await _squareMobilePaymentsSdkPlugin.startPayment(
        PaymentParameters(
            amountMoney: Money(amount: 100, currencyCode: CurrencyCode.eur),
            idempotencyKey: idempotencyKey
        ),
        PromptParameters(additionalPaymentMethods: List.empty(), mode: PromptMode.defaultMode));
    print('Payment successful:: $payment');
} catch (e) {
    print('Payment error: $e');
}

Payment parameters supports a number of additional attributes, which can be seen in the PaymentParameters definition. For error descriptions, visit the respective pages for iOS, and Android.

Optional: Use Mock Readers in Sandbox

You can use mock readers to take payments in Sandbox, which allows you to test the payment flow without moving real money. To do this, make sure you're using a Sandbox Application ID, access token, and location ID, available in the Developer console (see Step 3: Square Application ID and Access Token). Once you've configured your application to start in Sandbox, you can show or hide the mock reader as follows:

import 'package:square_mobile_payments_sdk/square_mobile_payments_sdk.dart';
//...
final _squareMobilePaymentsSdkPlugin = SquareMobilePaymentsSdk();

try {
    await _squareMobilePaymentsSdkPlugin.showMockReaderUI();
} catch (e) {
    print('Mock Reader UI error: $e');
}

//...
await _squareMobilePaymentsSdkPlugin.hideMockReaderUI();

Note that you might get an error if you try to call these methods outside of Sandbox, so you can handle the errors by using a try/catch block.

Tap to Pay Settings on iPhone

For iOS devices, you can manage Tap to Pay settings using the tapToPaySettings property. The following methods are available:

Link Apple Account

Before using Tap to Pay on iPhone, you need to link an Apple account:

import 'package:square_mobile_payments_sdk/square_mobile_payments_sdk.dart';
//...
final _squareMobilePaymentsSdkPlugin = SquareMobilePaymentsSdk();
//...
try {
      await _squareMobilePaymentsSdkPlugin.tapToPaySettings
          .linkAppleAccount();
    } catch (e, stackTrace) {
      print("Exception reader: $e");
    }

Relink Apple Account

If the Apple account needs to be relinked, use:

try {
      await _squareMobilePaymentsSdkPlugin.tapToPaySettings
          .relinkAppleAccount();
    } catch (e, stackTrace) {
      print("Exception reader: $e");
    }

Check if Apple Account is Linked

You can check if an Apple account is already linked:

try {
      bool isAppleAccountLinked =  await _squareMobilePaymentsSdkPlugin.tapToPaySettings.isAppleAccountLinked();

    } catch (e, stackTrace) {
      print("Exception reader: $e");
    }

Check Device Capability

To verify if the device supports Tap to Pay on iPhone:

    const isCapable = await _squareMobilePaymentsSdkPlugin.tapToPaySettings.isDeviceCapable();

Note: These methods are only available on iOS. Calling them on Android will result in an error.

---

📡 Offline Payments (Beta)

This is currently a Beta feature in the SDK. Additionally, use of offline payments requires Square sellers to opt in and agree to the terms of the feature.

🔧 Accessing Offline Features

You can manage offline payment capabilities using the SquareMobilePaymentsSdk singleton instance. The relevant namespaces are:

• settingsManager.paymentSettings – for checking offline availability and limits.
• paymentManager.offlinePaymentQueue – for accessing stored offline payments.

Example Usage

import 'package:square_mobile_payments_sdk/square_mobile_payments_sdk.dart';

final sdk = SquareMobilePaymentsSdk();

// Check if offline payments are allowed
final isAllowed = await sdk.settingsManager.paymentSettings.isOfflineProcessingAllowed();

// Get storage limits
final totalLimit = await sdk.settingsManager.paymentSettings.getOfflineTotalStoredAmountLimit();
final transactionLimit = await sdk.settingsManager.paymentSettings.getOfflineTransactionAmountLimit();

// Retrieve stored offline payments
final offlinePayments = await sdk.paymentManager.offlinePaymentQueue.getPayments();
final storedTotal = await sdk.paymentManager.offlinePaymentQueue.getTotalStoredPaymentAmount();

---

🧾 Seller Onboarding

Offline Payments support is Beta-only and requires seller opt-in.

To onboard a seller:

1. Send an email to: developerbetas@squareup.com
2. Include the following:
   • The seller's business name
   • The seller's email address (owner/admin of their Square account)
   • Your application ID

Square will contact the seller and provide an onboarding form. Once completed, Square will notify you when the seller is ready to process offline payments.

ℹ️ You can always check whether offline payments are allowed by calling isOfflineProcessingAllowed().

If you try to process an offline payment for a seller who hasn’t been onboarded, the SDK will return a USAGE_ERROR.

For more details, refer to: Square Android Offline Payments Docs