Reader SDK


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

Overview Permalink Get a link to this section

Reader SDK lets developers embed the Square checkout flow and accept in-person payments in custom applications using Square Readers. This simplifies chip and NFC payments, addresses EMV certification requirements, and makes PCI compliance easy. The SDK supports authorization, transaction processing, and Reader management. To learn about pricing for Reader SDK payments, read In-person payments using Square Readers.

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.

If you are taking payments with a Square Terminal, you must use the Terminal API to integrate payments in your application.

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 Seller 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 might not be in the line of sight of a seller 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 the following conditions are met:

    • It cannot be physically accessed by buyers outside the seller's normal business hours.

    • It is in the line of sight of the seller or one of the seller's workers.

    • The onsite seller and workers are trained to use the payment solution and are 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 seller Dashboard.

  • Reader SDK is not supported in the Square Sandbox. For more information, see Test Mobile Applications.

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

  • Reader SDK cannot process transactions when offline. A Reader SDK application must be connected to the Internet and be able to reach Square servers to process any payment cards taken by the application.

The Reader SDK cannot be directly integrated with the Payments API to get the payment details from a transaction. However, you can still use the transaction ID to get the payment details by making a set of related Square API calls. For more information, read Payments Integration.

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 four 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 the 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 applications to process payments on Square hardware on behalf of a specific Square account for a given location.

For more information, see Build with the Mobile Authorization API.

Working with transaction results using 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. For examples, see Migrate from the 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 supports a given version of Reader SDK for two 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 two-year life expectancy, Square contacts you in advance using the email address associated with your Square account.

Next steps Permalink Get a link to this section