An overview of the Square Sandbox, which can be used to simulate orders, invoices, payments, and transactions in a test environment.
Developer Tools

Square Sandbox

The Square Sandbox consists of a free, isolated server environment, a set of Sandbox seller test accounts, and a Sandbox Seller Dashboard for each account. A Sandbox is created for you when you create your first application in the Square Developer Dashboard. The Sandbox environment separates transactions from the production environment. Sandbox values are test values and cannot be used in a production environment.

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.

You can access the Sandbox in several ways. You can go between the Sandbox and the production environments by selecting the appropriate URL. The base URL for calling Sandbox endpoints is https://connect.squareupsandbox.com. When you move your application to production, you need production credentials and you need to use https://connect.squareup.com as the base URL.

In the Developer Dashboard, after you select your application, a toggle at the top of the page lets you select either Sandbox or production environments.

A screenshot showing the Sandbox/Production environment toggle for an application in the Developer Dashboard.

If you use API Explorer, you can select the Sandbox or production environment by using the toggle at the top of the page.

Important

The Sandbox does not accept valid credit cards. You must use test credit card values found in Sandbox Payments.

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.

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.

  • 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.

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.

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 left 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.