Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Sandbox

Test Square APIs With Sandbox

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

Backend

Square Sandbox
Permalink Get a link to this section

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

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.

Important

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 an access token before you can test your app 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, a set of test card numbers are used when you 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 https://connect.squareupsandbox.com/v2/payments 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.

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.

Digital wallet payments are not supported in the sandbox at this time.

Sandbox test nonces
Permalink Get a link to this section

If you do not want to generate a nonce with the Square Payment Form or In-App Payments SDK, you can generate a successful response from the payment endpoint supported in the sandbox that you are using.

v2 Sandbox (beta)
Permalink Get a link to this section

Use the Payments.CreatePayment endpoint for card and card on file (CoF) payments with the following test values:

API CallField NameValue
Payments API
(card)
card_noncecnon:card-nonce-ok
Payments API
(card on file)
customer_card_idccof:customer-card-id-ok
Customers API
(save card)
billing_address.postal_code94103

If you provide a sandbox nonce value to the CreateCustomerCard endpoint, you must provide "94103" as the postal code in the billing_address field or the request will fail and return an with an invalid postal code error.

Payment form test values for SCA
Permalink Get a link to this section

Use the SqPaymentForm.verifyBuyer function for card and card on file (CoF) SCA challenges with the following test values:

API CallField NameValueVerification Code
SqPaymentForm.verifyBuyer
(card)
card_noncecnon:card-nonce-requires-verification123456
SqPaymentForm.verifyBuyer
(card on file)
customer_card_idccof:customer-card-id-requires-verification123456

The SCA flow requires that the buyer provides a code sent to their mobile phone in an SMS message. When testing in the sandbox use the Verification Code to simulate the code sent via SMS.

Important

When testing the SCA flow in Sandbox (beta), be sure to initialize SqPaymentForm with a UK location ID.

The SCA flow and these test values are not supported in the legacy sandbox.

Note: For a complete list of sandbox nonce 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 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
Catalog
Inventory
Checkout
Customers
Employees
Labor
Locations
Payments
Orders
Refunds
Reporting
Transactions (Deprecated)
OAuth
Connect SDK
In-App Payments SDK
SqPaymentForm
Seller Dashboard - Sales
Seller Dashboard - Items
Seller Dashboard - Customers
v2 Webhooks (beta)

Important

To use a Connect SDK in the API sandbox environment, the API client base path must be set to https://connect.squareupsandbox.com. Refer to the Connect 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 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