Mobile Payments SDK

Applies to: Mobile Payments SDK - Android | Mobile Payments SDK - iOS | Reader SDK | Payments API | Orders API | OAuth API

Use the Mobile Payments SDK to accept in-person payments in iOS and Android applications.

The Mobile Payments SDK lets developers accept in-person payments using an embedded Square payment flow in iOS and Android applications. Sellers can take mobile payments using a Square Reader or Square Stand. The Mobile Payments SDK is the successor of the Reader SDK and offers the following benefits:

• Offline payments - Take and store payments locally on a mobile device. Offline payments allows you to build reliability into your application experience so sellers can keep taking payments even if devices lose their network connection. For more information, see Offline Payments for Android or Offline Payments for iOS.
• Integration with the Payments API - Payments taken with the Mobile Payments SDK are linked to Square Payment objects to enable:
  • The delayed capture of payments.
  • Partial authorization, which is used to split payments across multiple credit cards.
  • A configurable delay duration before voiding an authorization.
  • Collecting application fees.
  • Associating a payment with reference ID, team member ID, or location ID.
  • Accepting cash payments.
• Integration with the Orders API - Payments taken with the Mobile Payments SDK can be linked to Square Order objects to enable:
  • Itemization, where a payment is separated into different line items representing Catalog objects.
  • Applying price modifications such as taxes, discounts, or service charges on items.
  • Order-ahead functionality and sending SDK payments to Square Point of Sale for fulfillment.
• Sandbox support - Authorize the Mobile Payments SDK with a Square Sandbox account to test your integration with fake payments. You can simulate a virtual reader device to take test payments in the Square Sandbox without a physical card reader.
• Programmatic reader management - Programmatically pair card readers and monitor their battery level, state, and available payment methods using the SDK ReaderManager.
• Sample applications – Square provides Mobile Payments SDK sample applications for iOS (written in Swift using SwiftUI) and Android (written in Kotlin using Compose) to demonstrate a basic implementation of initialization, authorization, requesting permissions, and taking payments in the Sandbox and in production.

• The Mobile Payments SDK is currently available only for accounts based in the United States.
• Using the Mobile Payments SDK to implement payment solutions in unattended terminals or unattended kiosks is strictly prohibited. For example, an outdoor vending machine is unattended because it can be accessed by users outside of normal business hours and might not be in the line of sight of a seller or worker.
• The Mobile Payments SDK can only be used to implement payment solutions in attended terminals or attended kiosks. A terminal or kiosk is considered attended if all the following conditions are met:
  • It cannot be physically accessed by buyers outside the seller's normal business hours.
  • It's in the line of sight of the seller or one of the seller's workers.
  • The onsite seller and workers are trained to use the payment solution and are available to assist and support customers with completing transactions.

The Mobile Payments SDK is divided into four managers that provide specific areas of functionality:

• Authorization - The AuthorizationManager handles authorizing and deauthorizing your application to process payments on behalf of a Square seller using an OAuth access token and a location ID. OAuth access tokens are used to get authenticated and scoped access to any Square account. These tokens should be used even if you only plan to use the Mobile Payments SDK with your own Square account. For more information, see OAuth sample applications.
• Reader pairing and management - The ReaderManager allows you to pair card readers, listen for reader status updates, and perform actions on reader devices.
• Payments - The PaymentManager handles the payment flow for your application, which includes determining the available payment methods, taking payments, and accessing payments taken offline.
• Settings – The SettingsManager provides an optional device management UI that you can use in your application and provides details about the current SDK version.

At minimum, your application must have the following permissions to use the Mobile Payments SDK:

• MERCHANT_PROFILE_READ
• PAYMENTS_WRITE
• PAYMENTS_WRITE_IN_PERSON

If you plan to collect application fees, you must also have PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS permission.

Depending on its functionality and the other Square APIs used by your application, you might need to request other OAuth permissions from sellers. To learn which permissions are required for each API, see Square OAuth Permissions Reference.

The Mobile Payments SDK can be used to take payments with any version of Square Reader or Square Stand. Offline payment support is limited to the two most recent versions of Square Reader for contactless and chip, Square Reader for magstripe, and Square Stand second generation.

All Square Readers have a 16-digit serial number. Each Square Reader lists its version number in the 5th to 8th digits of the serial number like this XXXXMMMMXXXXXXXX. When you locate the serial number, refer to the MMMM sequence in the serial number.

Each Square Stand lists its model number in the 5th to 8th digits of the serial number like this XXXXMMMMXXXXXXXX. When you locate the serial number, refer to the MMMM sequence in the serial number.

The ReaderManager can be used to access the device serial number programmatically to determine the device version. A payment attempted with an offline flow on unsupported hardware results in an error.

Developers should make their best efforts to update their working version of the Mobile Payments SDK as soon as new versions are available. Square supports a given version of the Mobile Payments SDK for 2 years following its GA (General Availability) release, unless an update is required to address critical security updates or vulnerabilities or as otherwise deemed necessary by Square. If it becomes necessary to discontinue support for an SDK version before the 2-year life expectancy, Square contacts you in advance using the email address associated with your Square account.

• Build on Android
• Build on iOS