Reader SDK Overview
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 payments using Square Readers.
The Reader SDK does not support itemized transactions. Transactions processed with the Reader SDK appear on buyer receipts and in the Square Seller Dashboard with an optional note and the total transaction amount.
The 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 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 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.
Card payments with the Reader SDK must be $1 or greater. The minimum card payment accepted by the SDK is $1 (100). An attempt to charge a lower amount returns the
checkout_amount_below_card_payment_minimumerror. The amount limit does not apply to other tender types.
The Reader SDK only supports on-screen tipping. Digital receipts and tips can be configured in the Reader SDK. Tipping on printed receipts is not supported at this time.
The Reader SDK cannot issue refunds. Refunds can be issued programmatically using the Refunds API or manually in the Square Seller Dashboard.
The Reader SDK is not supported in the Square Sandbox. For more information, see Test Mobile Applications.
The Reader SDK does not 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 Integration.
The Reader SDK is not 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 is not 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 is no guarantee that they comply with Square's required security standards.
Verify that your device is supported (see Devices Compatible with the Square Magstripe and Chip Card Readers).
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 21 to 30. For runtime, the supported versions are 21 to 31.
For iOS, the compilation target currently supports versions 11 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:
Test the device with any expected software requirements before committing to using it for the Reader SDK.
Review Square's version support window.
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.
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.