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
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.
Field | Value |
---|---|
card_nonce | cnon:card-nonce-ok |
billing_address.postal_code | 94103 |
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
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.
Charge amount | Dispute reason |
---|---|
8801 | AMOUNT_DIFFERS |
8802 | CANCELLED |
8803 | DUPLICATE |
8804 | NO_KNOWLEDGE |
8805 | NOT_AS_DESCRIBED |
8806 | NOT_RECEIVED |
8807 | PAID_BY_OTHER_MEANS |
8808 | CUSTOMER_REQUESTS_CREDIT |
8809 | EMV_LIABILITY_SHIFT |
Gift Cards API
The Gift Cards API has several walkthroughs that use the Sandbox. These include the following:
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:
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:
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.
Device ID | Result | Details |
---|---|---|
jg260ny-11t2-4xy2-kg21-tl949bp350ca | Success | SAVE_CARD action type. This device id saves card against the customer ID. |
aafea9fa-350c-4ab2-b033-b2fbb672e712 | Failure | The 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-f8de0e864242 | Failure | The 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-513644de434d | Failure | The 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)
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
Device ID | Result | Details |
---|---|---|
9fa747a2-25ff-48ee-b078-04381f7c828f | Success | The 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-67f0c26346b0 | Success | The 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-8008dfe14e9 | Success | The 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-4a790e6f2789 | Success | The Interac credit card payment for the full amount is approved. Only supports CAD amounts. |
2b0b734b-b187-47f0-9d6f-288745210bdb | Success | The Interac credit card payment for the full amount is approved, with a 20% tip. Only supports CAD amounts. |
19a01fbd-3dcd-4d9f-a499-a641684af745 | Success | The eMoney/FeLiCa credit card payment for the full amount is approved, with a 20% tip. |
841100b9-ee60-4537-9bcf-e30b2ba5e215 | Failure | The 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-8eac603ffc5e | Failure | The 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-f42e36dab0c7 | Failure | The 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
The following example creates a checkout in the Sandbox:
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.
Device ID | Result | Details |
---|---|---|
f72dfb8e-4d65-4e56-aade-ec3fb8d33291 | Success | Complete 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-b2fbb672e712 | Failure | The 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-f8de0e864242 | Failure | The 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-513644de434d | Failure | The 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.