Test Square APIs in the Sandbox

Learn about the Square APIs that use the Sandbox for testing.

Many of the Square APIs have walkthroughs and examples that use the Sandbox test environment. The following is a quick reference to these walkthroughs and examples.

The Cards API has several walkthroughs using the Sandbox. These include the following:

• Create a Card on File from a Payment ID
• Create a Card on File and a Payment
• Create a Shared Card on File and Make a Payment

You can use a payment token generated with one of the test payment cards or you can use the values in the following table with calls to CreateCard and successfully create a card on file for a customer.

Build a Simple Catalog shows how to create a catalog in the Square Sandbox.

Use Sandbox device IDs and locations to test the following Devices API endpoints in the Square Sandbox:

• ListDevices returns a list of Square Terminals and filters devices based on location_id. The location_id represents a fake location for the test environment.
• GetDevice returns a positive test case with the given device ID. If you test with a device ID that isn't a Sandbox test value, GetDevice returns a NOT_FOUND error.

A dispute can be accepted or challenged with evidence using the Disputes API. Test the Disputes API shows how to validate that your Disputes API integration can complete these actions in the Square Sandbox.

Use these predefined payment amounts that map to specific dispute reasons. When you set one of these amounts in a CreatePayment request, Square generates a Sandbox dispute with the corresponding reason.

The amounts shown are in the lowest denomination of the currency you provide in the CreatePayment request. For example, for USD, the amount is in cents.

The Gift Cards API has several walkthroughs that use the Sandbox. These include the following:

• Sell a Gift Card
• Use a Gift Card

Build and Manage a Simple Inventory shows several examples using cURL to create an inventory in the Sandbox using the Inventory API.

You can use the Invoices API to create and manage invoices for orders created using the Orders API. You cannot use Square APIs to pay invoices or manage payment status.

In Create and Publish Invoices, which uses the Sandbox for testing, you use the Invoices API to create and publish invoices and then simulate the customer experience of paying an invoice.

Build with the Labor API shows how to use the Labor API to capture the start, breaks, and end of a team member's shift and the hourly rate for the shift.

Sellers use Square Loyalty to reward their customers and increase repeat business. Developers can use the Loyalty API to integrate Square Loyalty into third-party applications. You can use the Loyalty API to get information about loyalty programs, create loyalty accounts, enable buyers to earn and redeem points, and access loyalty event history.

The following walkthroughs use the Sandbox to test the Loyalty API:

• In this walkthrough, you use the Orders API to create orders and the Loyalty API to manage loyalty accounts and redeem loyalty points.
• In this walkthrough, you use the Catalog API to create items in your product catalog, the Orders API to create orders, and the Loyalty API to manage loyalty accounts and redeem loyalty points.

You test the sample walkthrough in the Square Sandbox environment. After creating a loyalty program, you need a phone number to set up a loyalty account. In the Sandbox, you provide a Sandbox phone number, instead of a real phone number, using the following format:

+1<valid-area-code>555<any-four-digits>

For example, +14255551111.

Your Sandbox account comes with one mock location per application. This location is unrelated to the production locations listed in the Square Developer Console.

The Sandbox location ID is listed on the Locations page for each application in the Developer Console. You can also retrieve the location ID programmatically by calling ListLocations with a Sandbox access token.

OAuth Walkthrough: Test Authorization with a Web Server lets you test each of the three stages of OAuth without using production seller accounts. The OAuth API is used to obtain permission from a seller to manage their resources.

Many of the code examples for the Orders API use the Sandbox. Some of these topics include the following:

• Create Orders
• Update Orders
• Retrieve Orders
• Pay for Orders
• Order-Ahead Application Use Case

Create a Subscription Plan and Manage Subscriptions is a cURL-based walkthrough where you set up a subscription program for a gym membership, create customer subscriptions, and verify customer billing.

Sandbox test values can be used to test Terminal checkouts in the Square Sandbox.

The Terminal API supports a collection of special device_id values you can use to simulate Terminal checkouts in the Sandbox without connecting to a physical Square Terminal. Successful Sandbox requests result in a payment generated in the Sandbox and shown in the Square Dashboard for your test account.

Use the following information to generate Sandbox terminal checkouts.

Sandbox test values can be used to test Terminal Interac refund requests in the Square Sandbox. Successful Sandbox requests result in a refund generated in the Sandbox and shown in the Square Dashboard for your test account.

Before you can test your integration for an Interac refund, you must create an Interac checkout/payment using an Interac device ID in the previous table.

Use the following to generate Sandbox Terminal Interac refund requests.

Sandbox test values can be used to test Terminal actions in the Square Sandbox.

The Terminal API supports a collection of special device_id values you can use to simulate Terminal actions in the Sandbox without connecting to a physical Square Terminal. The success case varies based on the action type. Failed requests simulate a customer canceling the operation, a server timed out, or the Square Terminal not picking up the request.

Use the following information to generate Sandbox Terminal actions.