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.

Cards API

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

Catalog API

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

Disputes API

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.

Gift Cards API

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

• Sell a Gift Card

• Use a Gift Card

Inventory API

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

Invoices 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 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

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

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.

Locations API

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

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

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 Sample Application

Subscriptions API

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)

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.

Terminal API (checkouts)

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

Example checkout request

The following example creates a checkout in the Sandbox:

curl -X POST \
  https://connect.squareupsandbox.com/v2/terminals/checkouts \
  -H 'Authorization: Bearer SANDBOX_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "idempotency_key": "RANDOM_STRING",
    "checkout": {
        "type": "DEVICE",
        "amount_money": {
            "amount": 100,
            "currency": "USD"
        },
        "reference_id": "YOUR REFERENCE ID",
        "device_options": {
            "device_id": "9fa747a2-25ff-48ee-b078-04381f7c828f"
        }
    }
}'

Terminal API (Interac refunds)

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

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.