Reader SDK

What It Does

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

Android
iOS
Flutter
React Native
Payments API
Reader SDK

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.

Did you know?

If you do not have a Square Reader, you can request a free Magstripe Reader or purchase a Square Reader online or in person.

Requirements and limitations
Permalink Get a link to this section

  • Reader SDK does not support 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.

  • Using Reader 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 may not be in the line of sight of a merchant or worker.

  • Reader SDK can only be used to implement payment solutions in attended terminals or attended kiosks. A terminal or kiosk is considered attended if all of the following conditions are met:

    • It cannot be physically accessed by buyers outside of the merchant’s normal business hours.

    • It is in the line of sight of the merchant or one or more of the merchant’s workers.

    • The onsite merchant and their workers are trained to use the payment solution and available to assist and support customers with completing transactions.

  • 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 Refunds API or manually in the Square Dashboard.

  • Reader SDK is not supported in the Square sandbox. See the Testing Mobile Apps guide for more information.

  • Reader SDK 1.3 does not support Payments API. Use the Transactions API to get payments generated by Reader SDK 1.3.

  • Reader SDK cannot process transactions when off-line: A Reader SDK app must be connected to the internet and be able to reach Square servers in order to process any payment cards taken by the app.

Reader SDK components
Permalink Get a link to this section

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
Permalink Get a link to this section

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 - Reader SDK 1
Permalink Get a link to this section

Transaction IDs and Transaction Client IDs can be used with the deprecated Square 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.

Any transaction created after the release of the Payments api in Square API v2019-08-14 can be retrieved using the Payments API GetPayment endpoint by Transaction.tenders[].id. The transaction tender must be a payment card, not cash or other tender. You can see examples in Migrate from Transactions API

Reader SDK Update Policy
Permalink Get a link to this section

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.

Try it out!

Try the quick start to see Reader SDK in action.