--- title: Capacitor Square Mobile Payments Plugin for Android & iOS description: Unofficial Capacitor plugin for Square Mobile Payments SDK to accept payments in your Android and iOS apps. tags: - Android - iOS search: boost: 2 faq: true status: new github_repo: capawesome-team/capacitor-plugins npm_package: "@capawesome/capacitor-square-mobile-payments" --- # Capacitor Square Mobile Payments Plugin Unofficial Capacitor plugin for [Square Mobile Payments SDK](https://developer.squareup.com/docs/mobile-payments-sdk).[^1]
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features This plugin provides a comprehensive integration with Square's Mobile Payments SDK for in-person payment processing. Here are some of the key features: - ๐Ÿ–ฅ๏ธ **Cross-platform**: Supports Android and iOS. - ๐Ÿ’ณ **Payment Processing**: Accept in-person payments with Square card readers. - ๐Ÿ“ฑ **Reader Management**: Pair, manage, and monitor Square card readers. - ๐Ÿ” **Secure Authorization**: OAuth-based authorization with Square access tokens. - ๐ŸŽจ **Flexible UI**: Choose between Square's default payment UI or build your own custom interface. - ๐Ÿ“Š **Real-time Updates**: Listen to reader status changes, pairing events, and payment completion. - ๐Ÿ’ฐ **Multiple Payment Methods**: Support for contactless (tap), chip (dip), swipe, and manual entry. - ๐ŸŒ **Online & Offline**: Process payments online or offline with automatic sync. - ๐Ÿงพ **Receipt Data**: Access card details, authorization codes, and EMV data for compliant receipts. - ๐Ÿ” **Up-to-date**: Always supports the latest Capacitor version. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The Square Mobile Payments plugin is typically used to accept in-person payments in a Capacitor app, for example: - **Point of sale**: Turn your app into a POS system that accepts tap, dip, swipe, and manually entered card payments with Square card readers. - **Tap to Pay on iPhone**: Accept contactless payments directly on an iPhone without additional hardware by linking a Square seller account with an Apple ID. - **Mobile and pop-up sales**: Pair, monitor, and manage Square readers for markets, food trucks, or events, and process payments offline with automatic sync when connectivity is limited. - **Compliant receipts**: Access card details, authorization codes, and EMV data of completed payments to generate compliant receipts. - **Testing without hardware**: Use the mock reader in debug builds to test the whole payment flow without a physical reader. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.1.x | >=8.x.x | Active support | ## Installation You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-square-mobile-payments` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome/capacitor-square-mobile-payments npx cap sync ``` ### Android #### SDK Initialization The Square Mobile Payments SDK must be initialized in your `Application` class before using the plugin. Create a custom `Application` class (if you don't already have one) and add the following code: 1. Create a file `MainApplication.java` in your app's `android/app/src/main/java//` directory: ```java package com.example.app; import android.app.Application; import com.squareup.sdk.mobilepayments.MobilePaymentsSdk; public class MainApplication extends Application { @Override public void onCreate() { super.onCreate(); MobilePaymentsSdk.initialize("YOUR_SQUARE_APPLICATION_ID", this); } } ``` **Note**: Replace `YOUR_SQUARE_APPLICATION_ID` with your actual Square Application ID. 2. Register the custom `Application` class in your `AndroidManifest.xml`: ```xml ``` #### Variables If needed, you can define the following project variable in your app's `variables.gradle` file to change the default version of the dependency: - `$squareMobilePaymentsSdkVersion` version of `com.squareup.sdk:mobile-payments-sdk` (default: `2.3.4`) This can be useful if you encounter dependency conflicts with other plugins in your project. ### iOS #### SDK Initialization The Square Mobile Payments SDK must be initialized in your `AppDelegate.swift` file before using the plugin. Add the following code to your `AppDelegate.swift`: 1. Import the `SquareMobilePaymentsSDK` at the top of the file: ```swift import SquareMobilePaymentsSDK ``` 2. Add the Square Application ID to your `Info.plist` file: ```xml SquareApplicationID YOUR_SQUARE_APPLICATION_ID_HERE ``` **Note**: Replace `YOUR_SQUARE_APPLICATION_ID_HERE` with your actual Square Application ID. Do not use the placeholder value in production. 3. Initialize the SDK in the `application(_:didFinishLaunchingWithOptions:)` method: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Initialize Square Mobile Payments SDK // Get the Square Application ID from info.plist if let squareAppID = Bundle.main.object(forInfoDictionaryKey: "SquareApplicationID") as? String, !squareAppID.isEmpty && squareAppID != "YOUR_SQUARE_APPLICATION_ID_HERE" { MobilePaymentsSDK.initialize( applicationLaunchOptions: launchOptions, squareApplicationID: squareAppID ) } // Override point for customization after application launch. return true } ``` #### Build Phases Add a new "Run Script Phase" in Xcode to run the Square SDK setup script by following these steps: 1. On the **Build Phases** tab for your application target in Xcode, choose the + button (at the top left of the pane). 2. Choose **New Run Script Phase**. The new run script phase should be the last build phase. 3. Expand the new Run Script phase and enter the following script: ``` FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}" "${FRAMEWORKS}/SquareMobilePaymentsSDK.framework/setup" ``` More details can be found in the [Square Mobile Payments SDK iOS setup guide](https://developer.squareup.com/docs/mobile-payments-sdk/ios). #### Privacy Descriptions Add the `NSLocationWhenInUseUsageDescription`, `NSBluetoothAlwaysUsageDescription`, and `NSMicrophoneUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why your app is requesting location, Bluetooth, and microphone permissions: ```xml NSBluetoothAlwaysUsageDescription We need Bluetooth access to connect to Square card readers. NSLocationWhenInUseUsageDescription We need your location to confirm payments are occurring in a supported Square location. NSMicrophoneUsageDescription We need microphone access to receive data from magstripe card readers. ``` ## Configuration No configuration required for this plugin. ## Usage The following examples show how to initialize and authorize the SDK, pair and list readers, start a payment, read the available card input methods, and listen for payment and reader events. ### Initialize and authorize the SDK Initialize the SDK with your Square location ID and authorize it with a Square access token. The `initialize(...)` method must be called before any other method: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const initializeSDK = async () => { await SquareMobilePayments.initialize({ locationId: 'YOUR_LOCATION_ID', }); await SquareMobilePayments.authorize({ accessToken: 'YOUR_ACCESS_TOKEN', }); }; ``` ### Check the authorization state Check whether the SDK is currently authorized, for example on app start: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const checkAuthorization = async () => { const { authorized } = await SquareMobilePayments.isAuthorized(); console.log('Authorized:', authorized); }; ``` ### Pair a Square reader Start the pairing process. The SDK searches for nearby readers and pairs with the first one found: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const pairReader = async () => { await SquareMobilePayments.startPairing(); }; ``` ### List the paired readers Get all paired readers with their serial number, model, and status: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const getReaders = async () => { const { readers } = await SquareMobilePayments.getReaders(); for (const reader of readers) { console.log('Reader:', reader.serialNumber, reader.model, reader.status); } }; ``` ### Start a payment Present the payment UI and process a payment with the specified parameters. Only one payment can be active at a time: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const processPayment = async () => { await SquareMobilePayments.startPayment({ paymentParameters: { amountMoney: { amount: 100, currency: 'USD', }, paymentAttemptId: crypto.randomUUID(), }, promptParameters: { mode: 'DEFAULT', additionalMethods: ['KEYED'], }, }); }; ``` ### Listen for payment events Listen for successful, failed, and cancelled payments to react to the result of a payment flow: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const listenToPaymentEvents = () => { SquareMobilePayments.addListener('paymentDidFinish', (event) => { console.log('Payment completed:', event.payment.id); console.log('Amount:', event.payment.amountMoney.amount); console.log('Card:', event.payment.cardDetails?.card.lastFourDigits); }); SquareMobilePayments.addListener('paymentDidFail', (event) => { console.error('Payment failed:', event.message); }); SquareMobilePayments.addListener('paymentDidCancel', (event) => { console.log('Payment cancelled'); }); }; ``` ### Listen for reader events Listen for reader status changes and changes to the available card input methods: ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const listenToReaderEvents = () => { SquareMobilePayments.addListener('readerWasAdded', (event) => { console.log('Reader added:', event.reader.serialNumber); }); SquareMobilePayments.addListener('readerDidChange', (event) => { console.log('Reader changed:', event.reader.serialNumber, event.change); }); SquareMobilePayments.addListener('availableCardInputMethodsDidChange', (event) => { console.log('Available methods:', event.cardInputMethods); }); }; ``` ### Get the available card input methods Read the card entry methods that are currently available based on the connected readers (e.g. tap, dip, swipe, or keyed entry): ```typescript import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments'; const getAvailableMethods = async () => { const { cardInputMethods } = await SquareMobilePayments.getAvailableCardInputMethods(); console.log('Available card input methods:', cardInputMethods); }; ``` ## API * [`initialize(...)`](#initialize) * [`authorize(...)`](#authorize) * [`isAuthorized()`](#isauthorized) * [`deauthorize()`](#deauthorize) * [`showSettings()`](#showsettings) * [`showMockReader()`](#showmockreader) * [`hideMockReader()`](#hidemockreader) * [`getSettings()`](#getsettings) * [`startPairing()`](#startpairing) * [`stopPairing()`](#stoppairing) * [`isPairingInProgress()`](#ispairinginprogress) * [`getReaders()`](#getreaders) * [`forgetReader(...)`](#forgetreader) * [`retryConnection(...)`](#retryconnection) * [`startPayment(...)`](#startpayment) * [`cancelPayment()`](#cancelpayment) * [`getAvailableCardInputMethods()`](#getavailablecardinputmethods) * [`linkAppleAccount()`](#linkappleaccount) * [`relinkAppleAccount()`](#relinkappleaccount) * [`isAppleAccountLinked()`](#isappleaccountlinked) * [`isDeviceCapable()`](#isdevicecapable) * [`checkPermissions()`](#checkpermissions) * [`requestPermissions()`](#requestpermissions) * [`addListener('readerPairingDidBegin', ...)`](#addlistenerreaderpairingdidbegin-) * [`addListener('readerPairingDidSucceed', ...)`](#addlistenerreaderpairingdidsucceed-) * [`addListener('readerPairingDidFail', ...)`](#addlistenerreaderpairingdidfail-) * [`addListener('readerWasAdded', ...)`](#addlistenerreaderwasadded-) * [`addListener('readerWasRemoved', ...)`](#addlistenerreaderwasremoved-) * [`addListener('readerDidChange', ...)`](#addlistenerreaderdidchange-) * [`addListener('availableCardInputMethodsDidChange', ...)`](#addlisteneravailablecardinputmethodsdidchange-) * [`addListener('paymentDidFinish', ...)`](#addlistenerpaymentdidfinish-) * [`addListener('paymentDidFail', ...)`](#addlistenerpaymentdidfail-) * [`addListener('paymentDidCancel', ...)`](#addlistenerpaymentdidcancel-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### initialize(...) ```typescript initialize(options: InitializeOptions) => Promise ``` Initialize the Square Mobile Payments SDK. This method must be called before any other method. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------- | | **`options`** | InitializeOptions | **Since:** 0.0.1 -------------------- ### authorize(...) ```typescript authorize(options: AuthorizeOptions) => Promise ``` Authorize the SDK with a Square access token. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------- | | **`options`** | AuthorizeOptions | **Since:** 0.0.1 -------------------- ### isAuthorized() ```typescript isAuthorized() => Promise ``` Check if the SDK is currently authorized. Only available on Android and iOS. **Returns:** Promise<IsAuthorizedResult> **Since:** 0.0.1 -------------------- ### deauthorize() ```typescript deauthorize() => Promise ``` Deauthorize the SDK and clear the current authorization. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### showSettings() ```typescript showSettings() => Promise ``` Show the Square settings screen. This displays a pre-built settings UI where merchants can view and manage their paired readers. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### showMockReader() ```typescript showMockReader() => Promise ``` Show the Mock Reader UI for testing. This displays a mock reader interface for testing payment flows without physical hardware. This is only for development and testing purposes and is therefore only available in debug builds. Only available on Android and iOS. **Since:** 0.1.1 -------------------- ### hideMockReader() ```typescript hideMockReader() => Promise ``` Hide the Mock Reader UI. Only available on Android and iOS. **Since:** 0.1.1 -------------------- ### getSettings() ```typescript getSettings() => Promise ``` Get the current SDK settings. Only available on Android and iOS. **Returns:** Promise<GetSettingsResult> **Since:** 0.0.1 -------------------- ### startPairing() ```typescript startPairing() => Promise ``` Start pairing with a Square reader. This initiates the reader pairing process. The SDK will search for nearby readers and pair with the first one found. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### stopPairing() ```typescript stopPairing() => Promise ``` Stop the reader pairing process. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### isPairingInProgress() ```typescript isPairingInProgress() => Promise ``` Check if a pairing process is currently in progress. Only available on Android and iOS. **Returns:** Promise<IsPairingInProgressResult> **Since:** 0.0.1 -------------------- ### getReaders() ```typescript getReaders() => Promise ``` Get a list of all paired readers. Only available on Android and iOS. **Returns:** Promise<GetReadersResult> **Since:** 0.0.1 -------------------- ### forgetReader(...) ```typescript forgetReader(options: ForgetReaderOptions) => Promise ``` Forget a paired reader. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | ForgetReaderOptions | **Since:** 0.0.1 -------------------- ### retryConnection(...) ```typescript retryConnection(options: RetryConnectionOptions) => Promise ``` Retry connecting to a reader. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------- | | **`options`** | RetryConnectionOptions | **Since:** 0.0.1 -------------------- ### startPayment(...) ```typescript startPayment(options: StartPaymentOptions) => Promise ``` Start a payment flow. This presents the payment UI and processes the payment using the specified parameters. Only one payment can be active at a time. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | StartPaymentOptions | **Since:** 0.0.1 -------------------- ### cancelPayment() ```typescript cancelPayment() => Promise ``` Cancel an ongoing payment. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### getAvailableCardInputMethods() ```typescript getAvailableCardInputMethods() => Promise ``` Get the currently available card input methods. This returns the card entry methods that are available based on the connected readers (e.g., TAP, DIP, SWIPE, KEYED). Only available on Android and iOS. **Returns:** Promise<GetAvailableCardInputMethodsResult> **Since:** 0.0.1 -------------------- ### linkAppleAccount() ```typescript linkAppleAccount() => Promise ``` Link a Square seller account with an Apple ID for Tap to Pay on iPhone. Presents an Apple sheet prompting the user to accept the Tap to Pay on iPhone terms and conditions. Only available on iOS. **Since:** 0.1.3 -------------------- ### relinkAppleAccount() ```typescript relinkAppleAccount() => Promise ``` Re-link a Square seller account with a different Apple ID. Presents an Apple sheet to change the associated Apple ID by showing the Tap to Pay terms and conditions again. Only available on iOS. **Since:** 0.1.3 -------------------- ### isAppleAccountLinked() ```typescript isAppleAccountLinked() => Promise ``` Check if an Apple ID is already linked to a Square seller account. Only available on iOS. **Returns:** Promise<IsAppleAccountLinkedResult> **Since:** 0.1.3 -------------------- ### isDeviceCapable() ```typescript isDeviceCapable() => Promise ``` Check if the device is capable of Tap to Pay on iPhone. Only available on iOS. **Returns:** Promise<IsDeviceCapableResult> **Since:** 0.1.3 -------------------- ### checkPermissions() ```typescript checkPermissions() => Promise ``` Check the current permission status. Only available on Android and iOS. **Returns:** Promise<PermissionStatus> **Since:** 0.0.1 -------------------- ### requestPermissions() ```typescript requestPermissions() => Promise ``` Request the required permissions. Only available on Android and iOS. **Returns:** Promise<PermissionStatus> **Since:** 0.0.1 -------------------- ### addListener('readerPairingDidBegin', ...) ```typescript addListener(eventName: 'readerPairingDidBegin', listenerFunc: ReaderPairingDidBeginListener) => Promise ``` Listen for reader pairing events. Only available on Android and iOS. | Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | **`eventName`** | 'readerPairingDidBegin' | | **`listenerFunc`** | ReaderPairingDidBeginListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('readerPairingDidSucceed', ...) ```typescript addListener(eventName: 'readerPairingDidSucceed', listenerFunc: ReaderPairingDidSucceedListener) => Promise ``` Listen for successful reader pairing events. Only available on Android and iOS. | Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | **`eventName`** | 'readerPairingDidSucceed' | | **`listenerFunc`** | ReaderPairingDidSucceedListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('readerPairingDidFail', ...) ```typescript addListener(eventName: 'readerPairingDidFail', listenerFunc: ReaderPairingDidFailListener) => Promise ``` Listen for failed reader pairing events. Only available on Android and iOS. | Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | **`eventName`** | 'readerPairingDidFail' | | **`listenerFunc`** | ReaderPairingDidFailListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('readerWasAdded', ...) ```typescript addListener(eventName: 'readerWasAdded', listenerFunc: ReaderWasAddedListener) => Promise ``` Listen for reader added events. Only available on Android and iOS. | Param | Type | | ------------------ | ------------------------------------------------------------------------- | | **`eventName`** | 'readerWasAdded' | | **`listenerFunc`** | ReaderWasAddedListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('readerWasRemoved', ...) ```typescript addListener(eventName: 'readerWasRemoved', listenerFunc: ReaderWasRemovedListener) => Promise ``` Listen for reader removed events. Only available on Android and iOS. | Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | **`eventName`** | 'readerWasRemoved' | | **`listenerFunc`** | ReaderWasRemovedListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('readerDidChange', ...) ```typescript addListener(eventName: 'readerDidChange', listenerFunc: ReaderDidChangeListener) => Promise ``` Listen for reader status and property changes. Only available on Android and iOS. | Param | Type | | ------------------ | --------------------------------------------------------------------------- | | **`eventName`** | 'readerDidChange' | | **`listenerFunc`** | ReaderDidChangeListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('availableCardInputMethodsDidChange', ...) ```typescript addListener(eventName: 'availableCardInputMethodsDidChange', listenerFunc: AvailableCardInputMethodsDidChangeListener) => Promise ``` Listen for available card input method changes. Only available on Android and iOS. | Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | **`eventName`** | 'availableCardInputMethodsDidChange' | | **`listenerFunc`** | AvailableCardInputMethodsDidChangeListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('paymentDidFinish', ...) ```typescript addListener(eventName: 'paymentDidFinish', listenerFunc: PaymentDidFinishListener) => Promise ``` Listen for successful payment completion events. Only available on Android and iOS. | Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | **`eventName`** | 'paymentDidFinish' | | **`listenerFunc`** | PaymentDidFinishListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('paymentDidFail', ...) ```typescript addListener(eventName: 'paymentDidFail', listenerFunc: PaymentDidFailListener) => Promise ``` Listen for failed payment events. Only available on Android and iOS. | Param | Type | | ------------------ | ------------------------------------------------------------------------- | | **`eventName`** | 'paymentDidFail' | | **`listenerFunc`** | PaymentDidFailListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### addListener('paymentDidCancel', ...) ```typescript addListener(eventName: 'paymentDidCancel', listenerFunc: PaymentDidCancelListener) => Promise ``` Listen for cancelled payment events. Only available on Android and iOS. | Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | **`eventName`** | 'paymentDidCancel' | | **`listenerFunc`** | PaymentDidCancelListener | **Returns:** Promise<PluginListenerHandle> **Since:** 0.0.1 -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise ``` Remove all listeners for this plugin. Only available on Android and iOS. **Since:** 0.0.1 -------------------- ### Interfaces #### InitializeOptions | Prop | Type | Description | Since | | ---------------- | ------------------- | ----------------------- | ----- | | **`locationId`** | string | The Square location ID. | 0.0.1 | #### AuthorizeOptions | Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------ | ----- | | **`accessToken`** | string | The Square access token. | 0.0.1 | #### IsAuthorizedResult | Prop | Type | Description | Since | | ---------------- | -------------------- | ---------------------------------------- | ----- | | **`authorized`** | boolean | Whether the SDK is currently authorized. | 0.0.1 | #### GetSettingsResult | Prop | Type | Description | Since | | ----------------- | --------------------------------------------------- | ------------------------ | ----- | | **`version`** | string | The SDK version. | 0.0.1 | | **`environment`** | Environment | The current environment. | 0.0.1 | #### IsPairingInProgressResult | Prop | Type | Description | Since | | ---------------- | -------------------- | --------------------------------------------------- | ----- | | **`inProgress`** | boolean | Whether a pairing process is currently in progress. | 0.0.1 | #### GetReadersResult | Prop | Type | Description | Since | | ------------- | ------------------------- | --------------------------- | ----- | | **`readers`** | ReaderInfo[] | The list of paired readers. | 0.0.1 | #### ReaderInfo | Prop | Type | Description | Since | | ------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----- | | **`serialNumber`** | string | The reader's serial number. | 0.0.1 | | **`model`** | ReaderModel | The reader's model. | 0.0.1 | | **`status`** | ReaderStatus | The reader's current status. | 0.0.1 | | **`firmwareVersion`** | string | The reader's firmware version. | 0.0.1 | | **`batteryLevel`** | number | The reader's battery level (0-100). | 0.0.1 | | **`isCharging`** | boolean | Whether the reader is currently charging. | 0.0.1 | | **`supportedCardInputMethods`** | CardInputMethod[] | The card input methods supported by this reader. | 0.0.1 | | **`unavailableReasonInfo`** | UnavailableReasonInfo | Additional information about why the reader is unavailable. Only present when status is ReaderUnavailable. | 0.0.1 | #### UnavailableReasonInfo | Prop | Type | Description | Since | | ------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ | ----- | | **`reason`** | UnavailableReason | The reason code why the reader is unavailable. | 0.0.1 | | **`message`** | string | A human-readable message describing why the reader is unavailable. | 0.0.1 | #### ForgetReaderOptions | Prop | Type | Description | Since | | ------------------ | ------------------- | ------------------------------------------ | ----- | | **`serialNumber`** | string | The serial number of the reader to forget. | 0.0.1 | #### RetryConnectionOptions | Prop | Type | Description | Since | | ------------------ | ------------------- | ---------------------------------------------------- | ----- | | **`serialNumber`** | string | The serial number of the reader to retry connection. | 0.0.1 | #### StartPaymentOptions | Prop | Type | Description | Since | | ----------------------- | --------------------------------------------------------------- | ----------------------- | ----- | | **`paymentParameters`** | PaymentParameters | The payment parameters. | 0.0.1 | | **`promptParameters`** | PromptParameters | The prompt parameters. | 0.0.1 | #### PaymentParameters | Prop | Type | Description | Default | Since | | ---------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----- | | **`amountMoney`** | Money | The amount of money to charge. | | 0.0.1 | | **`paymentAttemptId`** | string | A unique identifier for this payment attempt. This is used for idempotent payment requests. | | 0.0.1 | | **`processingMode`** | ProcessingMode | The processing mode for this payment. | ProcessingMode.AutoDetect | 0.0.1 | | **`referenceId`** | string | A user-defined reference ID to associate with the payment. | | 0.0.1 | | **`note`** | string | An optional note to add to the payment. | | 0.0.1 | | **`orderId`** | string | The Square order ID to associate with this payment. | | 0.0.1 | | **`tipMoney`** | Money | The tip amount. | | 0.0.1 | | **`applicationFee`** | Money | The application fee. | | 0.0.1 | | **`autocomplete`** | boolean | Whether to automatically complete the payment. If false, the payment will be authorized but not captured, requiring manual completion via the Payments API. | true | 0.0.1 | | **`delayDuration`** | string | The duration to delay before automatically completing or canceling the payment. Only applicable when autocomplete is false. | | 0.0.1 | | **`delayAction`** | DelayAction | The action to take when the delay duration expires. Only applicable when autocomplete is false. | | 0.0.1 | #### Money | Prop | Type | Description | Since | | -------------- | ----------------------------------------------------- | --------------------------------------------------------------- | ----- | | **`amount`** | number | The amount in the smallest currency unit (e.g., cents for USD). | 0.0.1 | | **`currency`** | CurrencyCode | The ISO 4217 currency code. | 0.0.1 | #### PromptParameters | Prop | Type | Description | Default | Since | | ----------------------- | ------------------------------------------------- | ------------------------------------ | ------------------------------- | ----- | | **`mode`** | PromptMode | The prompt mode. | PromptMode.Default | 0.0.1 | | **`additionalMethods`** | AdditionalPaymentMethod[] | Additional payment methods to allow. | [] | 0.0.1 | #### GetAvailableCardInputMethodsResult | Prop | Type | Description | Since | | ---------------------- | ------------------------------ | --------------------------------- | ----- | | **`cardInputMethods`** | CardInputMethod[] | The available card input methods. | 0.0.1 | #### IsAppleAccountLinkedResult | Prop | Type | Description | Since | | ------------ | -------------------- | ----------------------------------------------------------- | ----- | | **`linked`** | boolean | Whether an Apple ID is linked to the Square seller account. | 0.1.3 | #### IsDeviceCapableResult | Prop | Type | Description | Since | | ------------- | -------------------- | ------------------------------------------------------ | ----- | | **`capable`** | boolean | Whether the device is capable of Tap to Pay on iPhone. | 0.1.3 | #### PermissionStatus | Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`location`** | PermissionState | Permission state for accessing location. Required to confirm that payments are occurring in a supported Square location. | 0.0.1 | | **`recordAudio`** | PermissionState | Permission state for recording audio. Required to receive data from magstripe readers. | 0.0.1 | | **`bluetoothConnect`** | PermissionState | Permission state for Bluetooth connect. Required to receive data from contactless and chip readers. Only available on Android. | 0.0.1 | | **`bluetoothScan`** | PermissionState | Permission state for Bluetooth scan. Required to store information during checkout. Only available on Android. | 0.0.1 | | **`readPhoneState`** | PermissionState | Permission state for reading phone state. Required to identify the device sending information to Square servers. Only available on Android. | 0.0.1 | | **`bluetooth`** | PermissionState | Permission state for using Bluetooth. Only available on iOS. | 0.0.1 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | #### ReaderPairingDidFailEvent | Prop | Type | Description | Since | | ------------- | ------------------- | ------------------ | ----- | | **`code`** | string | The error code. | 0.0.1 | | **`message`** | string | The error message. | 0.0.1 | #### ReaderWasAddedEvent | Prop | Type | Description | Since | | ------------ | ------------------------------------------------- | -------------------------- | ----- | | **`reader`** | ReaderInfo | The reader that was added. | 0.0.1 | #### ReaderWasRemovedEvent | Prop | Type | Description | Since | | ------------ | ------------------------------------------------- | ---------------------------- | ----- | | **`reader`** | ReaderInfo | The reader that was removed. | 0.0.1 | #### ReaderDidChangeEvent | Prop | Type | Description | Since | | ------------ | ----------------------------------------------------- | --------------------------------- | ----- | | **`reader`** | ReaderInfo | The reader that changed. | 0.0.1 | | **`change`** | ReaderChange | The type of change that occurred. | 0.0.1 | #### AvailableCardInputMethodsDidChangeEvent | Prop | Type | Description | Since | | ---------------------- | ------------------------------ | --------------------------------- | ----- | | **`cardInputMethods`** | CardInputMethod[] | The available card input methods. | 0.0.1 | #### PaymentDidFinishEvent | Prop | Type | Description | Since | | ------------- | ------------------------------------------- | ---------------------- | ----- | | **`payment`** | Payment | The completed payment. | 0.0.1 | #### Payment | Prop | Type | Description | Since | | -------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----- | | **`id`** | string \| null | The unique identifier for this payment. For offline payments, this may be null until synced. | 0.0.1 | | **`type`** | PaymentType | The payment type. | 0.0.1 | | **`status`** | PaymentStatus | The payment status. | 0.0.1 | | **`amountMoney`** | Money | The amount paid. | 0.0.1 | | **`tipMoney`** | Money | The tip amount. | 0.0.1 | | **`applicationFee`** | Money | The application fee. | 0.0.1 | | **`referenceId`** | string | The reference ID provided in the payment parameters. | 0.0.1 | | **`orderId`** | string | The order ID associated with this payment. | 0.0.1 | | **`cardDetails`** | CardPaymentDetails | Card payment details. Only present for card payments. | 0.0.1 | | **`createdAt`** | string | The time the payment was created (ISO 8601 format). | 0.0.1 | | **`updatedAt`** | string | The time the payment was updated (ISO 8601 format). | 0.0.1 | #### CardPaymentDetails | Prop | Type | Description | Since | | ----------------------- | ----------------------------------------------------------- | ------------------------------- | ----- | | **`card`** | Card | The card information. | 0.0.1 | | **`entryMethod`** | CardInputMethod | The card entry method used. | 0.0.1 | | **`authorizationCode`** | string | The authorization code. | 0.0.1 | | **`applicationName`** | string | The EMV application name. | 0.0.1 | | **`applicationId`** | string | The EMV application identifier. | 0.0.1 | #### Card | Prop | Type | Description | Since | | --------------------- | ----------------------------------------------- | ---------------------------------------- | ----- | | **`brand`** | CardBrand | The card brand. | 0.0.1 | | **`lastFourDigits`** | string | The last four digits of the card number. | 0.0.1 | | **`cardholderName`** | string | The cardholder name. | 0.0.1 | | **`expirationMonth`** | number | The card expiration month (1-12). | 0.0.1 | | **`expirationYear`** | number | The card expiration year. | 0.0.1 | #### PaymentDidFailEvent | Prop | Type | Description | Since | | ------------- | ------------------------------------------- | ------------------- | ----- | | **`payment`** | Payment | The failed payment. | 0.0.1 | | **`code`** | string | The error code. | 0.0.1 | | **`message`** | string | The error message. | 0.0.1 | #### PaymentDidCancelEvent | Prop | Type | Description | Since | | ------------- | ------------------------------------------- | ---------------------- | ----- | | **`payment`** | Payment | The cancelled payment. | 0.0.1 | ### Type Aliases #### CurrencyCode string #### PermissionState 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' #### ReaderPairingDidBeginListener Callback to receive reader pairing start notifications. (): void #### ReaderPairingDidSucceedListener Callback to receive reader pairing success notifications. (): void #### ReaderPairingDidFailListener Callback to receive reader pairing failure notifications. (event: ReaderPairingDidFailEvent): void #### ReaderWasAddedListener Callback to receive reader added notifications. (event: ReaderWasAddedEvent): void #### ReaderWasRemovedListener Callback to receive reader removed notifications. (event: ReaderWasRemovedEvent): void #### ReaderDidChangeListener Callback to receive reader change notifications. (event: ReaderDidChangeEvent): void #### AvailableCardInputMethodsDidChangeListener Callback to receive available card input method change notifications. (event: AvailableCardInputMethodsDidChangeEvent): void #### PaymentDidFinishListener Callback to receive payment completion notifications. (event: PaymentDidFinishEvent): void #### PaymentDidFailListener Callback to receive payment failure notifications. (event: PaymentDidFailEvent): void #### PaymentDidCancelListener Callback to receive payment cancellation notifications. (event: PaymentDidCancelEvent): void ### Enums #### Environment | Members | Value | Description | Since | | ---------------- | ------------------------- | -------------------------------- | ----- | | **`Production`** | 'production' | Production environment. | 0.0.1 | | **`Sandbox`** | 'sandbox' | Sandbox environment for testing. | 0.0.1 | #### ReaderModel | Members | Value | Description | Since | | ------------------------ | ----------------------------------- | --------------------------------------- | ----- | | **`ContactlessAndChip`** | 'CONTACTLESS_AND_CHIP' | Square Reader for contactless and chip. | 0.0.1 | | **`Magstripe`** | 'MAGSTRIPE' | Square Reader for magstripe. | 0.0.1 | | **`Stand`** | 'STAND' | Square Stand. | 0.0.1 | | **`TapToPay`** | 'TAP_TO_PAY' | Tap to Pay on iPhone. | 0.1.3 | | **`Unknown`** | 'UNKNOWN' | Unknown reader model. | 0.0.1 | #### ReaderStatus | Members | Value | Description | Since | | ------------------------ | ----------------------------------- | -------------------------------------------------------------------- | ----- | | **`Ready`** | 'READY' | Reader is paired, connected, and ready to accept payments. | 0.0.1 | | **`ConnectingToSquare`** | 'CONNECTING_TO_SQUARE' | Reader is connecting to Square servers. | 0.0.1 | | **`ConnectingToDevice`** | 'CONNECTING_TO_DEVICE' | Reader is connecting to the mobile device. | 0.0.1 | | **`Faulty`** | 'FAULTY' | Reader has a hardware or connection error in an unrecoverable state. | 0.0.1 | | **`ReaderUnavailable`** | 'READER_UNAVAILABLE' | Reader is connected but unable to process payments. | 0.0.1 | #### CardInputMethod | Members | Value | Description | Since | | ----------- | -------------------- | --------------------------- | ----- | | **`Tap`** | 'TAP' | Contactless card tap (NFC). | 0.0.1 | | **`Dip`** | 'DIP' | EMV chip card insertion. | 0.0.1 | | **`Swipe`** | 'SWIPE' | Magnetic stripe swipe. | 0.0.1 | | **`Keyed`** | 'KEYED' | Manually keyed card entry. | 0.0.1 | #### UnavailableReason | Members | Value | Description | Since | | ------------------------------ | ----------------------------------------- | --------------------------------------------------------- | ----- | | **`BluetoothError`** | 'BLUETOOTH_ERROR' | Bluetooth connection issue. Only available on iOS. | 0.0.1 | | **`BluetoothFailure`** | 'BLUETOOTH_FAILURE' | Bluetooth failure. Only available on Android. | 0.0.1 | | **`BluetoothDisabled`** | 'BLUETOOTH_DISABLED' | Bluetooth is disabled. Only available on Android. | 0.0.1 | | **`FirmwareUpdate`** | 'FIRMWARE_UPDATE' | Reader firmware is updating. Only available on iOS. | 0.0.1 | | **`BlockingUpdate`** | 'BLOCKING_UPDATE' | Blocking firmware update. Only available on Android. | 0.0.1 | | **`ReaderUnavailableOffline`** | 'READER_UNAVAILABLE_OFFLINE' | Reader is unavailable offline. Only available on Android. | 0.0.1 | | **`DeviceDeveloperMode`** | 'DEVICE_DEVELOPER_MODE' | Device is in developer mode. Only available on Android. | 0.0.1 | | **`Unknown`** | 'UNKNOWN' | Unknown reason. | 0.0.1 | #### ProcessingMode | Members | Value | Description | Since | | ----------------- | --------------------------- | ------------------------------------------------------------------ | ----- | | **`AutoDetect`** | 'AUTO_DETECT' | Automatically detect the best processing mode (online or offline). | 0.0.1 | | **`OnlineOnly`** | 'ONLINE_ONLY' | Process the payment online only. | 0.0.1 | | **`OfflineOnly`** | 'OFFLINE_ONLY' | Allow offline payment processing. | 0.0.1 | #### DelayAction | Members | Value | Description | Since | | -------------- | ----------------------- | ---------------------------------------------------------- | ----- | | **`Complete`** | 'COMPLETE' | Automatically complete the payment when the delay expires. | 0.0.1 | | **`Cancel`** | 'CANCEL' | Automatically cancel the payment when the delay expires. | 0.0.1 | #### PromptMode | Members | Value | Description | Since | | ------------- | ---------------------- | ---------------------------------- | ----- | | **`Default`** | 'DEFAULT' | Use the default Square payment UI. | 0.0.1 | | **`Custom`** | 'CUSTOM' | Use a custom payment UI. | 0.0.1 | #### AdditionalPaymentMethod | Members | Value | Description | Since | | ----------- | -------------------- | -------------------------------- | ----- | | **`Keyed`** | 'KEYED' | Allow manually keyed card entry. | 0.0.1 | | **`Cash`** | 'CASH' | Allow cash payments. | 0.0.1 | #### ReaderChange | Members | Value | Description | Since | | ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------ | ----- | | **`BatteryDidBeginCharging`** | 'BATTERY_DID_BEGIN_CHARGING' | Reader battery started charging. Only available on iOS. | 0.0.1 | | **`BatteryDidEndCharging`** | 'BATTERY_DID_END_CHARGING' | Reader battery stopped charging. Only available on iOS. | 0.0.1 | | **`BatteryLevelDidChange`** | 'BATTERY_LEVEL_DID_CHANGE' | Reader battery level changed. Only available on iOS. | 0.0.1 | | **`BatteryCharging`** | 'BATTERY_CHARGING' | Reader battery charging status changed. Only available on Android. | 0.0.1 | | **`Added`** | 'ADDED' | Reader was added. Only available on Android. | 0.0.1 | | **`Removed`** | 'REMOVED' | Reader was removed. Only available on Android. | 0.0.1 | | **`StatusDidChange`** | 'STATUS_DID_CHANGE' | Reader status changed. | 0.0.1 | #### PaymentType | Members | Value | Description | Since | | ------------- | ---------------------- | ------------------------------------------------- | ----- | | **`Online`** | 'ONLINE' | Payment processed online. | 0.0.1 | | **`Offline`** | 'OFFLINE' | Payment processed offline. | 0.0.1 | #### PaymentStatus | Members | Value | Description | Since | | --------------- | ------------------------ | ------------------------------------------------------------------ | ----- | | **`Completed`** | 'COMPLETED' | Payment was completed successfully. | 0.0.1 | | **`Approved`** | 'APPROVED' | Payment was approved but not yet completed. | 0.0.1 | | **`Canceled`** | 'CANCELED' | Payment was canceled. | 0.0.1 | | **`Failed`** | 'FAILED' | Payment failed. | 0.0.1 | | **`Pending`** | 'PENDING' | Payment is pending. | 0.0.1 | #### CardBrand | Members | Value | Description | Since | | --------------------- | ------------------------------- | ---------------------------- | ----- | | **`Visa`** | 'VISA' | Visa card. | 0.0.1 | | **`Mastercard`** | 'MASTERCARD' | Mastercard. | 0.0.1 | | **`AmericanExpress`** | 'AMERICAN_EXPRESS' | American Express card. | 0.0.1 | | **`Discover`** | 'DISCOVER' | Discover card. | 0.0.1 | | **`DiscoverDiners`** | 'DISCOVER_DINERS' | Discover Diners card. | 0.0.1 | | **`Jcb`** | 'JCB' | JCB card. | 0.0.1 | | **`UnionPay`** | 'UNION_PAY' | UnionPay card. | 0.0.1 | | **`Interac`** | 'INTERAC' | Interac card. | 0.0.1 | | **`Eftpos`** | 'EFTPOS' | Eftpos card. | 0.0.1 | | **`Other`** | 'OTHER' | Other or unknown card brand. | 0.0.1 | ## FAQ ### Which platforms are supported by this plugin? The plugin supports Android and iOS. There is no Web implementation, since the Square Mobile Payments SDK requires native hardware access to card readers. ### How can I test payments without a physical card reader? Use the `showMockReader()` method to display a mock reader interface for testing payment flows without physical hardware. It is only intended for development and testing purposes and is therefore only available in debug builds. You can hide it again with `hideMockReader()`. ### What permissions does the plugin require? The plugin requires location access to confirm that payments are occurring in a supported Square location, Bluetooth access to connect to Square card readers, and, on iOS, microphone access to receive data from magstripe readers. You can check and request the required permissions with `checkPermissions()` and `requestPermissions()`, and the corresponding privacy descriptions must be added to your `Info.plist` on iOS (see [Installation](#installation)). ### Does the plugin support Tap to Pay on iPhone? Yes, on iOS you can link a Square seller account with an Apple ID using `linkAppleAccount()`, which presents an Apple sheet with the Tap to Pay on iPhone terms and conditions. Use `isDeviceCapable()` to check whether the device supports Tap to Pay on iPhone, and `relinkAppleAccount()` to switch to a different Apple ID. ### Why do the plugin methods fail before I call any of them? The Square Mobile Payments SDK must be initialized natively with your Square Application ID before the plugin can be used: in a custom `Application` class on Android and in the `AppDelegate` on iOS (see [Installation](#installation)). Additionally, `initialize(...)` must be called before any other plugin method, followed by `authorize(...)` with a Square access token. ### Can I process payments without an internet connection? Yes, the plugin supports processing payments online or offline with automatic sync. Note that for offline payments, the payment `id` may be `null` until the payment has been synced. ### Can I use this plugin with Ionic, React, Vue or Angular? Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins - [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/): Support in-app purchases in your Capacitor app. - [Superwall](https://capawesome.io/docs/sdks/capacitor/superwall/): Present remotely-configured paywalls to drive subscriptions. - [Wallet](https://capawesome.io/docs/sdks/capacitor/wallet/): Add passes to Apple Wallet and Google Wallet. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/square-mobile-payments/CHANGELOG.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/square-mobile-payments/LICENSE). [^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Square, Inc. or any of their affiliates or subsidiaries.