Reader SDK

What It Does

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 to simplify chip and NFC payments, address EMV certification requirements, and make PCI compliance easy. The SDK supports authorization, transaction processing, and Reader management.

Reader SDK is available for native development on iOS and Android and as plugins for Flutter and React Native.

Requirements and limitations

  • Reader SDK does not supported itemized transactions. Transactions processed with Reader SDK appear on buyer receipts and in the Square Dashboard with an optional note and the total transaction amount.
  • 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 transactions cannot be attributed to an employee. Reader SDK transactions are attributed to the authorized location but cannot be tied to a specific employee login.
  • 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.

Reader SDK components

Reader SDK supports in-person payments by embedding the Square checkout flow and Reader settings manager in mobile applications. The workflow includes 4 key elements:

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

Mobile authorization codes

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.

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.

Reader SDK Quick Start >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow