Test Square APIs With Sandbox

Learn about using the Square sandbox environment in developing and testing an integration.

Square Sandbox
Permalink Get a link to this section

The 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 Portal.

The Square API sandbox improves the app testing experience for a developer by providing these key features:

  • Sandbox Seller Dashboard: Provides a merchant view of testing account activity.

  • Support for Connect APIs and SDKs: Sandbox now supports most Connect v2 APIs and SDKs.

  • Multiple sandbox test accounts: Sandbox test accounts include 1 default test account and up to 4 additional accounts available for simulated payments in other countries.

  • OAuth support: The portal generates an OAuth access token for each testing account to simplify testing with OAuth tokens.

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

To test your app in the sandbox you must use:

  • The environment domain - for all REST and SDK calls

  • application credentials

Sandbox test accounts
Permalink Get a link to this section

A sandbox test account simulates a seller with access to their app in the sandbox.

When a developer creates a Square developer account and opens the Developer Portal for the first time, they are provisioned with a Default Sandbox Test Account configured with the country of the production developer account.


The Default Sandbox Test Account is automatically authorized to use any app under development that is configured with the Sandbox Personal Access Token. This token is scoped to use all permissions.

You need to get the sandbox personal access token for your app and configure your app with it before you can test in the sandbox.

Up to 4 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 app in the Developer Portal.

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 on the endpoint.

Payments are processed in a simulator and 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 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.

Note: For a complete list of sandbox payments test values, see Sandbox Test Values . To see test values for Disputes management in the

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 testing account.

image-test sandbox-01@2x

Developers may test new API versions in sandbox before upgrading production code and pinning their production app to a new API version. API versions in the sandbox are identical to their matching versions in production.

OAuth support in sandbox
Permalink Get a link to this section

Each sandbox test account that accesses an app in the sandbox must be authorized to use the app. This authorization is represented by an OAuth access token that is generated for each account/app pair by the Developer Portal. In production, access tokens are generated by using the Authorization API flow. Although authorization is handled by the sandbox, a developer can also 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/app pair scoped to permissions selected by the developer. A developer can also revoke account access to an app in the developer portal. When testing an application, API calls are made with that access token and operation results are shown in the sandbox seller dashboard for the account.

The developer Sandbox Personal Access Token can only be used to authorize the Default Sandbox Test Account and can be used with any app. All other test accounts need a unique access token for each account/app pair.

Sandbox Connect API support
Permalink Get a link to this section

Sandbox support is available for the following Square APIs:

Connect v2 APISDKSquare Service
Transactions (Deprecated)
Connect SDK
In-App Payments SDK
Seller Dashboard - Sales
Seller Dashboard - Items
Seller Dashboard - Customers
v2 Webhooks (beta)


To use a Connect SDK in the API sandbox environment, the API client base path must be set to Refer to the Connect SDK GitHub repository for instructions to set the base path.

Sandbox seller dashboard
Permalink Get a link to this section

Square hosts a seller dashboard for each of the testing accounts created in the Developer Portal . A dashboard provides a merchant view of API calls and is accessed by clicking Launch from the testing accounts list in the Developer Portal of the Square application developer.

image-test sandbox-02@2x

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

Did you know?

A user is automatically logged out of the Sandbox Seller Dashboard after a period of inactivity. If you are logged out of the Sandbox Seller Dashboard, you should close the Seller Dashboard tab in your browser and then re-launch the dashboard from the Sandbox Test Account in the Developer Portal.

image-test sandbox-03@2x

The Default Sandbox Test Account seller dashboard shows the results of all API operations from any app configured with the developer account Sandbox Personal Access Token.

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 testing account.

Get started

Create testing accounts in the developer portal