Reader SDK

Applies to: Reader SDK - Android | Reader SDK - iOS | Terminal API | Refunds API | Payments API | Mobile Authorization API

Use the Reader SDK to take in-person payments from mobile applications using an embedded checkout flow and Square hardware.

The 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, see In-person payment pricing.

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

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

• The Reader SDK is currently available only for accounts based in the United States.
• The Reader SDK doesn't support itemized transactions. Transactions processed with the Reader SDK appear on buyer receipts and in the Square Dashboard with an optional note and the total transaction amount.
• Authorization requests for accounts based outside the United States return an error.
• Using the 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.
• The 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's 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.
• The Reader SDK only supports on-screen tipping. Digital receipts and tips can be configured in the Reader SDK. Tipping on printed receipts isn't supported at this time.
• The Reader SDK cannot issue refunds. Refunds can be issued programmatically using the Refunds API or manually in the Square Dashboard.
• The Reader SDK isn't supported in the Square Sandbox. For more information, see Testing for supported countries.
• The Reader SDK doesn't support the Payments API. Use the Transactions API to get payments generated by the Reader SDK.
• The 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, see Payments API Integration.

The Reader SDK isn't compatible to run on custom devices from OEMs that violate Square's security rules or on devices that grant root access to the mobile device operating system code and kernel. As a result, these devices cannot connect to a Contactless and Chip Reader.

The following additional considerations apply when trying to run the SDK on custom devices:

• The Reader SDK cannot run on custom operating systems.
• The Reader SDK isn't supported to run on rooted or jailbroken devices.
• Square prohibits using any software that provides the ability to record or capture screen data or that results in elevated privileges.
• Square recommends running the Reader SDK on devices from large mobile device manufacturers such as Google, Samsung, or HTC.
• Avoid running on devices from smaller OEMs because there's no guarantee that they comply with Square's required security standards.
• Verify that your device is supported (see Devices Compatible with Square Reader for Contactless and Chip).
• Supported OS versions should be the latest or as close to the latest as possible.
• Review Square's support window for the OS version and confirm support for the compilation target version and the runtime version:
  • For Android, the compilation target currently supports versions 24 to 33. For runtime, the supported versions are 24 to 33.
  • For iOS, the compilation target currently supports versions 14 and later.

If the mobile application runs on an uncommon device manufacturer, be sure to test connecting to the Square Reader over Bluetooth before investing in the device.

The following steps are recommended to verify your device:

1. Test the device with any expected software requirements before committing to using it for the Reader SDK.
2. Review Square's version support window.
3. Ensure that you can pair the device with the Reader SDK over Bluetooth.

The 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 the 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.

In the context of the 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.

The Reader SDK supports the Refunds API, which requires a payment ID to issue a refund. The Reader SDK returns a transaction ID and one or more tender IDs. To issue a refund, use the tender ID as the PAYMENT_ID when you call the RefundPayment endpoint. To get a list of payments and their IDs, call the ListPayments endpoint.

For more information about how to call a refund, see Refund Payments.

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

Developers should make their best efforts to update their working version of the Reader SDK as soon as new versions are available. Square supports a given version of the 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 contacts you in advance using the email address associated with your Square account.

• Reader SDK Quickstart
• Video: Take Payments with the Reader SDK