Reader SDK

How It Works

This topic looks deeper 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 application requests a mobile authorization code from an authorization service and uses the returned code to authorize Reader SDK.

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

    Did you know?

    The reader device may be in sleep mode due to inactivity. If so, the seller must wake the reader by pressing the small button on the edge. Read Square Contactless and Chip Card Reader Troubleshooting

  3. The mobile application 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 application. If the user does not 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, Reader SDK is deauthorized (such as, when the user signs out of the application). To ensure that no data is lost, Reader SDK cannot be deauthorized if there are pending transactions waiting to be synced.


Checkout workflow Permalink Get a link to this section

Checkout parameters Permalink Get a link to this section

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, 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 (such as, purchase totals and tender details), successful 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), 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.