Migrate from the Reader SDK

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

Learn how to migrate applications from the Reader SDK to use the Mobile Payments SDK.

Link to section


The Mobile Payments SDK is the successor of the Reader SDK, offering a streamlined and PCI-compliant payment flow for iOS and Android mobile applications. To take advantage of the enhanced features of the Mobile Payments SDK and to ensure future application compatibility and support, developers are encouraged to migrate their Reader SDK applications to the Mobile Payments SDK as soon as possible. The following sections cover the major technical differences between the Reader SDK and the Mobile Payments SDK, but you're encouraged to thoroughly test your application when upgrading.

Link to section

OAuth authentication

The Reader SDK requires a mobile authorization code generated with the Mobile Authorization API to authorize the SDK, in addition to the standard OAuth flow. In contrast, the Mobile Payments SDK doesn't require a mobile authorization code, only the standard PKCE OAuth flow. The Mobile Authorization API isn't required to use the Mobile Payments SDK.

When a seller signs in to Square using your authorization URL and approves your authorization request, your redirect URL receives the authorization response containing an authorization code. This code is used to call the ObtainToken endpoint, which returns the Square seller's access_token in the response. Use this access token with the Mobile Payments SDK AuthorizationManager.authorize method and when calling other Square APIs. To learn more about the OAuth workflow, see OAuth API.

Link to section

Payments, not transactions

The Mobile Payments SDK is built on the Payments API, enabling a comprehensive integration with the rest of the Square Developer platform. In contrast, the Reader SDK is built on the now deprecated Transactions API, which shouldn't be used moving forward. Working with payment instead of transactions allows you to benefit from all the capabilities offered by this and other APIs, including:

  • Collecting developer application fees (a portion of each payment your application processes using the Mobile Payments SDK).
  • The delayed capture of payments and a configurable delay duration before completing or voiding a payment.
  • Adding tips, discounts, and taxes using the Orders API.
  • Associating a payment with a reference_id or team_member_id.

For more information about modifying your application to use payments instead of transactions, see Migrate from the Transactions API.

Link to section

Reader management and settings screen

Another change from the Reader SDK is the addition of programmatic reader management in the Mobile Payments SDK. You can use the ReaderManager to pair readers and get a list of readers connected to the mobile device running your application. The ReaderInfo class provides details about connected readers such as model, battery percentage, serial number, and card entry methods. You can use this class to create custom screens to display information about the status of readers to application users or use a Square-provided settings screen for quick integration.