A quick reference for walkthroughs for various Square APIs that use the Sandbox for testing.
Developer Tools

Test Square APIs in the Sandbox

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.

Important

Some of the APIs require special test values when creating transactions in the Sandbox, especially when processing test payments. For more information about these test payment values, see Sandbox Payments.

Cards API Permalink Get a link to this section

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

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

FieldValue
card_noncecnon:card-nonce-ok
billing_address.postal_code94103

Important

If you use a Sandbox test payment token with the CreateCard endpoint, you must provide 94103 as the postal code in the billing_address field or the request fails and returns an invalid postal code error.

Catalog API Permalink Get a link to this section

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

Disputes API Permalink Get a link to this section

A dispute can be accepted or challenged with evidence using the Disputes API. This walkthrough 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.

Charge amountDispute reason
8801AMOUNT_DIFFERS
8802CANCELLED
8803DUPLICATE
8804NO_KNOWLEDGE
8805NOT_AS_DESCRIBED
8806NOT_RECEIVED
8807PAID_BY_OTHER_MEANS
8808CUSTOMER_REQUESTS_CREDIT
8809EMV_LIABILITY_SHIFT

Gift Cards API Permalink Get a link to this section

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

Inventory API Permalink Get a link to this section

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

Invoices API Permalink Get a link to this section

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 the Create and Publish Invoices walkthrough, 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.

Labor API Permalink Get a link to this section

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.

Loyalty API Permalink Get a link to this section

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:

For example, +14255551111.

Locations API Permalink Get a link to this section

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

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

OAuth API Permalink Get a link to this section

OAuth Walkthrough: Authorization Using a Test Account 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.

Orders API Permalink Get a link to this section

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

Subscriptions API Permalink Get a link to this section

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.

Terminal API (actions) Permalink Get a link to this section

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 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 for saving a card on file.

Device ID
Result
Details
jg260ny-11t2-4xy2-kg21-tl949bp350caSuccessSAVE_CARD action type. This device id saves card against the customer ID.
aafea9fa-350c-4ab2-b033-b2fbb672e712FailureThe terminal action is canceled by the buyer.
Note: This is the behavior when a terminal action attempt fails and the buyer cancels on the device.
e371fb66-29a2-45a6-a928-f8de0e864242FailureThe terminal action is timed out by Square.
Note: This action immediately times out the terminal action as if the timeout period has elapsed.
7647344e-aea2-4cff-ac53-513644de434dFailureThe terminal action is not picked up by Square Terminal and can be canceled by the developer.
This behavior simulates an offline Terminal and can be canceled by the developer. If not canceled, this terminal action times out.

Terminal API (checkouts) Permalink Get a link to this section

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 without connecting to a physical Square Terminal. Successful Sandbox requests result in a payment generated in the Sandbox and shown in the Seller Dashboard for your test account.

Use the following information to generate Sandbox terminal checkouts.

Terminal checkout test device IDs Permalink Get a link to this section

Device ID
Result
Details
9fa747a2-25ff-48ee-b078-04381f7c828fSuccessThe credit card payment for the full amount is approved.
Approved payments are up to $25 USD. Larger amounts fail and the checkout remains PENDING until it times out.
Note: This behavior is indistinguishable from initial failures followed by a successful payment.
22cd266c-6246-4c06-9983-67f0c26346b0SuccessThe credit card payment for the full amount is approved, with a 20% tip.
Approved payments are up to $25 USD. Larger amounts fail and the checkout remains PENDING until it times out.
4mp4e78c-88ed-4d55-a269-8008dfe14e9SuccessThe Square gift card payment for the full amount is approved. Approved payments are up to $25 USD. Larger amounts fail and the checkout remains PENDING until it times out.
388b5a08-a77c-48ef-ad2a-4a790e6f2789SuccessThe Interac credit card payment for the full amount is approved. Only supports CAD amounts.
2b0b734b-b187-47f0-9d6f-288745210bdbSuccessThe Interac credit card payment for the full amount is approved, with a 20% tip. Only supports CAD amounts.
19a01fbd-3dcd-4d9f-a499-a641684af745SuccessThe eMoney/FeLiCa credit card payment for the full amount is approved, with a 20% tip.
841100b9-ee60-4537-9bcf-e30b2ba5e215FailureThe checkout is canceled by the buyer.
Note: This is the behavior when individual payment attempts fail and the buyer cancels on the device.
0a956d49-619a-4530-8e5e-8eac603ffc5eFailureThe checkout is timed out by Square.
Note: This action immediately times out the checkout as if the timeout period has elapsed.
da40d603-c2ea-4a65-8cfd-f42e36dab0c7FailureThe checkout is not picked up by a Square Terminal and can be canceled by the developer.
This behavior simulates an offline Terminal and can be canceled by the developer. If not canceled, this checkout times out.

Example checkout request Permalink Get a link to this section

The following example creates a checkout in the Sandbox:

Terminal API (Interac refunds) Permalink Get a link to this section

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

Terminal Interac refund test device IDs Permalink Get a link to this section

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

Device ID
Result
Details
f72dfb8e-4d65-4e56-aade-ec3fb8d33291SuccessComplete card-present refund.
The refund is limited to the amount of the original payment and can only be applied to payments that require card-present refunds.
aafea9fa-350c-4ab2-b033-b2fbb672e712FailureThe terminal refund is canceled by the buyer.
Note: This is the behavior when individual refund attempts fail and the buyer cancels on the device.
e371fb66-29a2-45a6-a928-f8de0e864242FailureThe terminal refund is timed out by Square.
Note: This action immediately times out the terminal refund as if the timeout period has elapsed.
7647344e-aea2-4cff-ac53-513644de434dFailureThe terminal refund is not picked up by Square Terminal and can be canceled by the developer.
This behavior simulates an offline Terminal and can be canceled by the developer. If not canceled, this terminal refund times out.

Note

Use the Refunds API to request refunds on all other card networks.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.