Test Square APIs With Sandbox
Learn about using the Square sandbox environment in developing and testing an integration.
The v2 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.
To test your app in the sandbox you must use:
The v2 Sandbox environment domain -
connect.squareupsandbox.comfor all REST and SDK calls
v2 Sandbox application credentials
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.
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
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.
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.
Use the Payments.CreatePayment endpoint for card and card on file (CoF) payments with the following test values:
|API Call||Field Name||Value|
|Payments API |
|Payments API |
(card on file)
|Customers API |
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.
Use the SqPaymentForm.verifyBuyer function for card and card on file (CoF) SCA challenges with the following test values:
|API Call||Field Name||Value||Verification Code|
(card on file)
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.
When testing the SCA flow in v2 Sandbox, 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
When application Sandbox Settings are enabled, a developer can set the Sandbox API version used by an application when authorized by a testing account.
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.
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 support is available for the following Square APIs:
|Connect v2 API||SDK||Square Service|
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
https://connect.squareupsandbox.com. Refer to the Connect SDK GitHub
repository README.md for instructions to set the base path.
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.
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.
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.
Create testing accounts in the developer portal