Take Payments

Reader SDK Overview

Take in-person payments from mobile apps using an embedded checkout flow and Square hardware.

Reader SDK lets developers embed the Square checkout flow and accept in-person payments in custom apps using Square Readers. The SDK supports authorization, transaction processing, and Reader management.

Reader SDK is available for native development on iOS and Android. Build payment solutions with Reader SDK to simplify chip and NFC payments, address EMV certification requirements, and make PCI compliance easy.

Requirements and limitations

  • Reader SDK is only available for accounts based in the United States. Authorization requests for accounts based outside the United States return an error.
  • Reader SDK may not be used for unattended terminals. Using Reader SDK to implement payment solutions in unattended terminals or kiosks (for example, vending machines) is strictly prohibited.
  • Reader SDK only supports on-screen tipping. Digital receipts and tips can be configured in Reader SDK. Tipping on printed receipts is not supported at this time.
  • Reader SDK cannot issue refunds. Refunds can be issued programmatically using the Transactions API or manually in the Square Dashboard.
  • Reader SDK is not supported in the Square sandbox. See the Testing Mobile Apps guide for testing recommendations.

How to use it — the Reader SDK data model

Reader SDK supports in-person payments by embedding the Square checkout flow in mobile applications. Reader SDK works with the following key data structures:

  • Mobile authorization code — requested from the Mobile Authorization API and used to authorize Reader SDK for payment processing.
  • Checkout parameters — used to configure the tipping, signature, and receipt options shown in the checkout flow.
  • Checkout result — provides transaction metadata for successful payments and troubleshooting metadata for failed payments.
  • Reader settings — manages connection state and setting details for Square Readers.

Additionally, to work with Square Readers, apps must have the device permissions noted below. If the required device permissions are not granted when the checkout flow initiates, Reader SDK prompts the user to grant the necessary permissions (Android) or returns an error message (iOS).

Android device permission Purpose
Location To confirm payments are occurring in a supported country.
Audio To connect Magstripe Readers.
Bluetooth To connect Contactless Readers.
Device Storage To store information during checkout.
Phone Access To identify the device sending information to Square servers.
iOS device permission Purpose
Location To confirm payments are occurring in a supported country.
Microphone To connect Magstripe Readers.

Mobile authorization code

In the context of Reader SDK, authorization refers to using the SDK with a mobile authorization code from the Mobile Authorization API. Mobile authorization tokens allow custom mobile apps to process payments on Square hardware on behalf of a specific Square account for a given location.

See the Mobile Authorization API Guide for more information.

Checkout parameters

Reader SDK collects payment through the checkout flow. The checkout flow is a sequence of screens used to verify the tender amount, select and split tenders, collect tip, request signatures, and return change. The checkout parameters determine which screens comprise the checkout flow and which options are available in addition to setting the total payment amount.

Checkout configuration options include:

  • setting tender (payment) types.
  • whether or not to accept split tenders (paying with more than one method).
  • whether or not to require a signature.
  • whether or not to show the tip collection screen.
  • pre-calculated tip amounts.
  • adding a note.
  • skipping the receipt screen.

By default, Reader SDK accepts card tenders, does not accept split tenders, requires a signature, and disables tipping.

Checkout result

In addition to the general transaction details (e.g., purchase totals, tender details), successful Reader SDK checkout responses may include up to 2 unique, Square-issued IDs:

  • Transaction ID — present only for successful transactions that include a card tender.
  • Transaction Client ID — present for all successful transactions.

When the checkout flow fails (or is canceled), Reader SDK returns user displayable error details (error code and message) and debugging information (debug code and message) rather than a transaction summary.

Reader settings

In addition to pairing/unpairing Square Readers, Reader SDK includes UI support for the following management tasks:

  • automatic updates — automatically updates the Reader firmware when connected and new versions are released.
  • troubleshooting — provides pairing feedback in the UI. A successful pairing displays a confirmation and a failed pairing displays error details.

How it works — the Reader SDK process flow

Reader SDK must be authorized with a mobile authorization code before it can be used to connect a Reader or accept payments. In general, authorizing Reader SDK and completing a transaction involves the following steps:

  1. The mobile app requests a mobile authorization code from an authorization service and uses the returned authorization code to authorize Reader SDK.
  2. The mobile app initializes Reader SDK and starts the Square Reader Settings flow to connect a Square Reader.
  3. The mobile app constructs a checkout parameter object and uses Reader SDK to start the checkout flow.
  4. Reader SDK walks the user through the checkout flow.
  5. Reader SDK syncs transaction details with Square servers. Transactions that include a card tender sync instantaneously. All other transactions sync asynchronously.
  6. Reader SDK returns the transaction details (or error details) to the mobile app. If the user does not tap "New Sale", or anywhere else on the Transaction Complete screen, the Reader SDK checkout flow automatically completes after 2 seconds.
  7. The mobile app displays the transaction results.
  8. At some future time, Reader SDK is deauthorized (e.g., when the user logs out of the application). To ensure no data is lost, Reader SDK cannot be deauthorized if there are pending transactions waiting to be synced.
Readersdk process flow

Working with Transaction Results

Transaction IDs and Transaction Client IDs can be used with the Connect v2 Transactions API to load transaction details for issuing refunds and reconciling daily totals.

Transaction IDs are directly retrievable through the RetrieveTransaction endpoint, but are only returned for transactions that include a valid card tender. Transaction Client IDs are always set but are only indirectly retrievable by searching the results of a ListTransactions call.

Reader SDK Update Policy

Developers should make best efforts to update their working version of Reader SDK as soon as new versions are available. Square will support a given version of Reader SDK for 2 years following its initial 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 will contact you in advance via the email address associated with your Square account.


Android Setup Guide

Build custom solutions with Reader SDK for Android.

iOS Setup Guide

Build custom solutions with Reader SDK for iOS.

Ask for help on Stack Overflow or join our Slack channel