How It Works

Applies to: Reader SDK - Android | Reader SDK - iOS

Learn about the Reader SDK process flow and checkout flow and how they work.

The Reader SDK must be authorized with a mobile authorization code before it can be used to connect a Reader or accept payments. In general, authorizing the Reader SDK and completing a transaction involves the following steps:

1. The mobile application requests a mobile authorization code from an authorization service and uses the returned code to authorize the Reader SDK.

2. The mobile application initializes the Reader SDK and starts the Square Reader settings flow to connect a Square Reader.

   Note

   The Reader might be in sleep mode due to inactivity. If so, the seller must wake up the Reader by pressing the small button on the edge. For more information, see Square Reader for Contactless and Chip Troubleshooting.

3. The mobile application constructs a checkout parameter object and uses the Reader SDK to start the checkout flow.

4. The Reader SDK walks the user through the checkout flow.

5. The Reader SDK syncs transaction details with Square servers. Transactions that include a card tender sync instantaneously. All other transactions sync asynchronously.

6. The Reader SDK returns the transaction details (or error details) to the mobile application. If the user doesn't choose New Sale, or anything else on the Transaction Complete screen, the Reader SDK checkout flow automatically completes after 2 seconds.

7. The mobile application displays the transaction results.

8. At some future time, the Reader SDK is deauthorized (such as when the user signs out of the application). To ensure that no data is lost, the Reader SDK cannot be deauthorized if there are pending transactions waiting to be synced.

   

The Reader SDK collects payments through the checkout workflow. The checkout workflow is a sequence of screens used to verify the tender amount, select and split tenders, collect tips, request signatures, and return change. Checkout parameters determine which screens comprise the checkout flow and which options are available in addition to setting the total payment amount.

Checkout configuration options include:

• Setting tender (payment) types.
• Whether to accept split tenders (paying with more than one method).
• Whether to require a signature.
• Whether to show the tip collection screen.
• Precalculated tip amounts.
• Adding a note.
• Skipping the receipt screen.

By default, the Reader SDK accepts card tenders, doesn't accept split tenders, requires a signature, and disables tipping.

In addition to the general transaction details (such as purchase totals and tender details), the Reader SDK checkout responses can include up to two unique Square-issued IDs:

• The transaction ID, which is present only for successful transactions that include a card tender.
• The transaction client ID, which is present for all successful transactions.

When the checkout flow fails (or is canceled), the Reader SDK returns user-displayable error details (an error code and message) and debugging information (a debug code and message) rather than a transaction summary.