Sandbox

Test in the Sandbox

Learn about using the Square Sandbox environment to develop and test a Square API integration.

Square Sandbox
Permalink Get a link to this section

The Square Sandbox consists of an isolated server environment, a set of Sandbox 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 Square Sandbox improves the application testing experience for developers by providing these key features:

  • Sandbox Seller Dashboard. Provides a seller view of test account activity.

  • Support for Square APIs and SDKs. The Sandbox now supports most Square APIs and SDKs.

  • Multiple Sandbox test accounts. Sandbox test accounts include one default account and up to four additional accounts that are available for simulated payments in other countries.

  • OAuth support. The Developer Dashboard generates an OAuth access token for each test account to simplify testing with OAuth tokens.

The Sandbox environment enables simulated business activity and lets developers build, test, and monitor applications integrated with Square. The environment maintains resources and processes that are identical to production except that state and API operations are isolated from production and external payment card processors.

To test your application in the Sandbox, you must use:

  • The Square Sandbox environment domain: connect.squareupsandbox.com for all REST and SDK calls.

  • Square Sandbox application credentials.

Sandbox test accounts
Permalink Get a link to this section

A Sandbox test account simulates a seller with access to their application in the Sandbox.

When a developer creates a Square developer account and opens the Developer Dashboard for the first time, the developer is provisioned with a default Sandbox test account configured with the country of the production developer account.

Important

The default Sandbox test account is automatically authorized to use any application under development that is configured with the Sandbox access token. This token is scoped to use all permissions.

You need to get the Sandbox access token for your application and configure your application with it before you can test in the Sandbox.

Up to four additional Sandbox test accounts can be created per developer account. A developer selects a country for each account and the Sandbox enforces locale-specific API and service limitations based on the chosen country. These additional accounts must be individually authorized to use an application in the Developer Dashboard.

Test payments
Permalink Get a link to this section

Real payment cards are not supported in the Sandbox. Instead, use a card number from the set of Sandbox test card numbers to generate a nonce with the payment form or the In-App Payments SDK in the Sandbox. To complete a test payment, call CreatePayment.

Payments are processed in a simulator and the resulting sales appear in the Sandbox Seller Dashboard for the account. Test cards behave exactly like real payment cards except that:

  • They can be used to simulate payments in another country.

  • They do not trip risk/compliance signals, leading to frozen card accounts.

  • The receipt_url associated with a Sandbox payment is not valid and does not link to an actual Sandbox payment receipt.

  • Payments cannot be refunded in the Sandbox Seller Dashboard. You must use the API to refund payments.

Note

The default Sandbox test account cannot be deleted. All transaction history in this account persists for the life of the account. All other test accounts can be deleted.

For a complete list of Sandbox payments test values, see Sandbox Test Values.

API versioning
Permalink Get a link to this section

When application Sandbox settings are enabled, a developer can set the Sandbox API version used by an application when authorized by a test account.

image-test sandbox-01@2x

Developers can test new API versions in the Sandbox before upgrading production code and setting their production application to a new API version. API versions in the Sandbox are identical to their matching versions in production.

OAuth support in the Sandbox
Permalink Get a link to this section

Each Sandbox test account that accesses an application in the Sandbox must be authorized to use the application. This authorization is represented by an OAuth access token that is generated for each account/application pair by the Developer Dashboard. In production, access tokens are generated by using the Authorization API flow. Although authorization is handled by the Sandbox, a developer can use the Authorization API to authorize a Sandbox seller account and get a Sandbox access token.

The Sandbox creates access and refresh tokens for the account/application pair scoped to the permissions selected by the developer. A developer can also revoke account access to an application in the Developer Dashboard. When testing an application, API calls are made with the application's access token and the operation results are shown in the Sandbox Seller Dashboard for the account.

The developer personal access token can only be used to authorize the default Sandbox test account and can be used with any application. All other test accounts need a unique access token for each account/application pair.

Sandbox Square API support
Permalink Get a link to this section

Sandbox support is available for the following Square platform components:

Square APISDKSquare Service
Catalog
Checkout
Customers
Devices
Disputes
Employees
Inventory
Labor
Loyalty
Locations
OAuth
Orders
Payments
Refunds
Reporting
Team
Terminal
Transactions (Deprecated)
Square SDK
In-App Payments SDK
Payment form
Seller Dashboard - Sales
Seller Dashboard - Items
Seller Dashboard - Customers
v2 Webhooks (beta)

Important

To use a Square SDK in the Sandbox environment, the API client's base path must be set to https://connect.squareupsandbox.com. Refer to the Square SDK GitHub repository README.md for instructions to set the base path.

Sandbox Seller Dashboard
Permalink Get a link to this section

Square hosts a Seller Dashboard for each test account created in the Developer Dashboard. A dashboard provides a seller view of API calls and is accessed by clicking Open from the test accounts list in the Developer Dashboard.

image-launch sandbox-02@2x

The Sandbox Seller Dashboard is the seller view of Sandbox activity from a Square integration perspective. The Seller Dashboard lets a developer verify sales, catalog, and inventory operations performed in an integration. A developer can also create customers and catalog items for use in app testing. In Sandbox mode, the Seller Dashboard shows a yellow banner above the toolbar.

Did you know?

A user is automatically signed out of the Sandbox Seller Dashboard after a period of inactivity. If you are signed out of the Sandbox Seller Dashboard, you should close the Seller Dashboard tab in your browser and then restart the Seller Dashboard from the Sandbox test account in the Developer Dashboard.

image-test sandbox-03@2x

The default Sandbox test account in the Seller Dashboard shows the results of all API operations from any app configured with the Sandbox personal access token in the developer account.

If you want to show activity from only one integration test, create a new test account and authorize it to use your app under development. When you are done testing, you can delete the new test account.

Get started

Create test accounts in the Developer Dashboard.