Reader SDK

How It Works

A deeper look at Reader SDK.

Reader SDK process flow
Permalink Get a link to this section

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 Reader SDK and completing a transaction involves the following steps:

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

  2. The mobile app initializes Reader SDK and starts the Square Reader Settings flow to connect a Square Reader.

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

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

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

  6. Reader SDK returns the transaction details (or error details) to the mobile app. If the user does not tap "New Sale", or anywhere else on the Transaction Complete screen, the Reader SDK checkout flow automatically completes after 2 seconds.

  7. The mobile app displays the transaction results.

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


The Checkout workflow
Permalink Get a link to this section

Checkout parameters
Permalink Get a link to this section

Reader SDK collects payment through the checkout workflow. The checkout workflow is a sequence of screens used to verify the tender amount, select and split tenders, collect tip, 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 or not to accept split tenders (paying with more than one method).

  • whether or not to require a signature.

  • whether or not to show the tip collection screen.

  • pre-calculated tip amounts.

  • adding a note.

  • skipping the receipt screen.

By default, Reader SDK accepts card tenders, does not accept split tenders, requires a signature, and disables tipping.

Checkout result
Permalink Get a link to this section

In addition to the general transaction details (e.g., purchase totals, tender details), successful Reader SDK checkout responses may include up to 2 unique, Square-issued IDs:

  • Transaction ID — present only for successful transactions that include a card tender.

  • Transaction Client ID — present for all successful transactions.

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