Developer Tools

Sandbox Overview

The Square Sandbox consists of an isolated server environment, a set of Sandbox seller test accounts, and a Sandbox Seller Dashboard for each account. Every developer gets their own Sandbox that they set up and use in the Square Developer Dashboard. The Sandbox environment separates transactions from the production environment.

Overview Permalink Get a link to this section

Use the Square Sandbox to create transactions in the seller test account by calling Square APIs using API Explorer or your own code. You can use the Sandbox to take payments, create an inventory and subscriptions, and simulate sales and transactions using payment information specifically for use with the Sandbox.

The default test account is a seller account in which you are automatically authorized to perform actions and access data. All your applications have been pre-authorized for all OAuth permissions. Because the default test account uses the same access token as the applications you create, you do not need to use an access token that is specific to a seller. If you create additional seller test accounts, you must use the access token assigned to that seller account.

There is a Seller Dashboard for each test account you create using the Developer Dashboard. The Seller Dashboard provides a seller view of results of the API calls and is accessed by choosing Open from the test accounts list in the Developer Dashboard.

A diagram that shows Sandbox test account relationships.

You can use the Sandbox to:

  • Test new versions of Square APIs before using them in production.

  • Test using a specified API version. You specify the version of the application you run in the Sandbox.

  • Test payment scenarios.

  • Simplify the OAuth process so you receive authorization to make calls on a seller's test account when you set up the account.

  • Run API calls for unsupported regions.

Sandbox limitations Permalink Get a link to this section

The Square Sandbox can be great for exercising test scenarios, but it does have some limitations. For example, Square hardware, such as a POS terminal, cannot be used with the Sandbox.

Sandbox limitations include the following:

  • Square applications (first-party applications), including Square for Restaurants, Square Point of Sale, and Square Invoices, are not supported for testing in the Sandbox.

  • Sending email notifications is not supported.

  • Connection V1 API calls are not supported, including the V1 Employees API and V1 Settlements API.

  • The Reader SDK 1.0 and Point of Sales API are not supported.

  • The Snippets API and Sites API are not supported.

  • Settlements data is not available.

  • Customer settings are not supported.

  • Testing the Terminal API is supported, but testing on the device itself is not.

  • Gift cards generated by the Gift Cards API cannot be used with Virtual Terminal in the Sandbox. In addition, physical gift cards cannot be created or managed.

The Seller Dashboard, when used with a test account in the Sandbox, has limitations as well. These limitations include the following:

  • Receipts are not generated.

  • Refunds can be viewed but cannot be issued.

  • Viewing or editing subscriptions is not supported.

  • Sending emails is not supported.

  • Viewing the booking URL is not supported.

  • The Payments API currently only supports using a token that represents a test Square gift card. It does not accept a gift card created using the Gift Cards API.

Create a Sandbox test account Permalink Get a link to this section

Create Sandbox test accounts and access the Sandbox Seller Dashboard in the Developer Dashboard.

The Developer Dashboard lets you create up to four test accounts in addition to the default Sandbox test account.

  1. Sign in to the Developer Dashboard to create test accounts.

  2. Choose Add to create a new Sandbox test account.

    A screenshot showing the Developer Dashboard main page with the test account's Add button highlighted.

Authorize a Sandbox test account Permalink Get a link to this section

The application OAuth page lets you authorize a Sandbox test account to use your application with the permission scope you set in the authorization. In testing, you can bypass the production OAuth Authorization API call flow by using the access token generated for each Sandbox test account you create.

  1. Sign in to the Developer Dashboard and choose the application that you want a test account to be authorized to use.

  2. On the application page, you can toggle between the Sandbox and Production accounts. Choose Sandbox.

  3. In the navigation pane, choose OAuth, and then choose Authorize an Account.

  4. In the Authorize an Account dialog box, choose a Sandbox test account to authorize.

  5. Choose the permissions that you want the account to have, and then choose Save.

Note

If you want to change the permission scope that you authorized for a Sandbox test account, you must revoke the existing authorization and create a new one.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.