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.
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.
The Build a Simple Catalog walkthrough shows how to create a catalog in the Sandbox.
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 |
The Gift Cards API has several walkthroughs that use the Sandbox. These include the following:
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 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.
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:
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 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 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.
Many of the code examples for the Orders API use the Sandbox. Some of these topics include the following:
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 sandbox 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.
Device ID | Result | Details |
|---|---|---|
| 9fa747a2-25ff-48ee-b078-04381f7c828f | Success | The checkout is successfully completed by the buyer using a credit card. 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 checkout is successfully completed by the buyer using a Square gift card. 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 | An Interac credit card payment for the full amount is approved. Only supports CAD amounts. |
| 2b0b734b-b187-47f0-9d6f-288745210bdb | Success | An Interac credit card payment for the full amount is approved, with a 20% tip. Only supports CAD amounts. |
| 19a01fbd-3dcd-4d9f-a499-a641684af745 | Success | An eMoney/FeLiCa credit card payment for the full amount is approved. |
| 819f8d79-961e-4097-8f70-ef70b3e7db28 | Success | The Afterpay 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. |
| cae0ee02-f83b-11ec-b939-0242ac120002 | Success | The PayPay QR code payment for the full amount is approved. Note: The sandbox location must be based in Japan. |
| 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. |
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 Seller 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.
Device ID | Result | Details |
|---|---|---|
| f72dfb8e-4d65-4e56-aade-ec3fb8d33291 | Success | The Interac refund request is successfully completed by the buyer. 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.
Sandbox test values can be used to test Terminal actions in the Square Sandbox.
Important
Terminal actions are currently in beta.
The Terminal API supports a collection of special device_id values you can use to simulate Terminal actions in 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.
Device ID | Result | Details |
|---|---|---|
| jg260ny-11t2-4xy2-kg21-tl949bp350ca | Success | The Terminal action successfully completes the request. |
| 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. |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.