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.

The Mobile Payments SDK is the successor of the Reader SDK, providing a simple and PCI-compliant payment flow for iOS and Android applications. Developers should migrate their Reader SDK applications to the Mobile Payments SDK to benefit from new features and ensure continued support before the retirement of the Reader SDK on December 31, 2025. The following sections cover the major differences between the Reader SDK and the Mobile Payments SDK. When migrating your application, you can also reference the Mobile Payments SDK sample applications for iOS and Android.

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.

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 payments 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.

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.

The Reader SDK includes a built-in workflow for saving a card on file. The Mobile Payments SDK relies on the Cards API to save a card to a customer's profile.

To store a card on file with the Mobile Payments SDK:

1. Authorize a payment with a credit card. This payment can be delayed and canceled later if you don’t want to charge the customer.
2. Note the payment_id value.
3. Use the CreateCard endpoint to save the card on file. For more information, see Create a Card on File from a Payment ID.

To take multiple payments or accept different forms of payment on a single order, your application must take each payment separately with the Mobile Payments SDK. You should build your own checkout flow UI to give buyers the option of split tender payments, create separate PaymentParameters for each payment, and then make individual calls to PaymentManager.startPayment() (iOS) or PaymentManager.startPaymentActivity() (Android).

If you're using the Orders API and want to split a payment for an order, each payment made with the Mobile Payments SDK must include the orderID in the PaymentParameters and autocomplete must be set to false. To complete the payments, call the PayOrder endpoint, specifying each of the payment IDs. For more information, see Pay for Orders.

Tips can be added to a payment before or after authorization by including an optional tipMoney value in the payment parameters or by calling the UpdatePayment endpoint and setting tip_money prior to completing a delayed payment. The Mobile Payments SDK doesn't include a built-in tipping UI, so you should build your own tipping UI for your application.

Signatures aren't required for inserted, tapped, or swiped card payments. The Mobile Payments SDK doesn't include a signature collection workflow.

Your application must provide buyers the option to receive a digital or printed receipt. Receipts aren't sent directly by Square. You can generate receipts for customers using cardDetails from the SDK's payment response or send customers a link to the Square-generated receipt_url, found in the Square Payment object. This URL is only present on COMPLETED payments.