Square Sandbox

Learn about the Square Sandbox, which can be used to simulate orders, invoices, payments, and transactions in a test environment.

The Square Sandbox consists of a free, isolated server environment, a set of Sandbox seller test accounts, and a Sandbox Square Dashboard for each account. A Sandbox is provisioned for each application you create in the Square Developer Console. The Sandbox environment separates transactions from the production environment. Sandbox values are test values and can't 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 Console, after you select your application, a toggle at the top of the page lets you select either Sandbox or production environments.

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

The default test account is a seller account in which you're 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 don't 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 Square Dashboard for each test account you create using the Developer Console. The Square 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 Console.

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, can't 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, aren't supported for testing in the Sandbox.
• The Reader SDK 1.0 and Point of Sales API aren't supported.
• The Snippets API and Sites API aren't supported.
• Settlements data isn't available.
• Customer settings aren't supported.
• Testing the Terminal API is supported, but testing on the device itself isn't.
• Gift cards generated by the Gift Cards API can't be used with Virtual Terminal in the Sandbox. In addition, physical gift cards can't be created or managed.

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

• Receipts aren't generated.
• Refunds can be viewed but can't be issued.
• Viewing or editing subscriptions isn't supported.
• Sending emails isn't supported.
• Viewing the booking URL isn't supported.

The Square Dashboard doesn't support the Banking tab. As a result, Balance and App Fee Reporting are also not supported.

Use of the sandbox environment is free of charge. You can make an unlimited number of free sandbox API calls. There are no payment processing fees for sandbox payments given that cards aren't actually charged and payments are never actually processed by a live bank.

In the production environment, some API calls require that your application user has a subscription to the related Square software-as-a-service. All production payment processing through Square APIs have a processing fee. For information about payments pricing, see Payments Pricing with Square APIs and SDKs.

Create Sandbox test accounts and access the Sandbox Square Dashboard in the Developer Console.

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

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

2. In the left pane, choose Sandbox text accounts, and then choose New sandbox text account to create a new Sandbox test account.

   

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