Sandbox Test Values
Test Square API operations in the Square Sandbox using test values.
On this page
Sandbox test values are used to test the client and server sides of payment processing in the Square Sandbox.
Sandbox payments
Square platform clients, such as the payment form and In-App Payments applications, accept payment cards and return one-time use encrypted nonces to be submitted to Square API payment endpoints to take payments. You can avoid testing your code with a real payment card by testing in the Sandbox.
Test client-side card-present logic in your payment form or In-App Payments application by using test credit card numbers to generate nonces for use with the Square API payments and card-on-file endpoints in the Sandbox.
If you do not need to test your client-side nonce-generation logic, use the nonces provided in the Square endpoint testing section to submit payments in the Sandbox with test nonces.
Client-side testing
You can use test credit cards with the payment form and In-App Payments SDK to input card numbers that generate a testable payment nonce.
Card present success state values
The Sandbox supports a collection of credit card numbers for all Square-supported card brands for simulating the client side of payment scenarios.
Test cards
Brand | Number | CVV | Verification Code |
---|---|---|---|
Visa | 4111 1111 1111 1111 | 111 | ❌ |
Visa EU | 4310 0000 0020 1019 | 111 | 123456 |
MasterCard | 5105 1051 0510 5100 | 111 | ❌ |
MasterCard EU | 5500 0000 0020 1016 | 111 | 123456 |
Discover | 6011 0000 0000 0004 | 111 | ❌ |
Discover EU | 6011 0000 0020 1016 | 111 | 123456 |
Diners Club | 3000 000000 0004 | 111 | ❌ |
JCB | 3569 9900 1009 5841 | 111 | ❌ |
American Express | 3400 000000 00009 | 1111 | ❌ |
American Express EU | 3700 000002 01014 | 1111 | 123456 |
China UnionPay | 6222 9888 1234 0000 | 123 | ❌ |
Square Gift Card | 7783 3200 0000 0000 | ❌ | ❌ |
Notes:
You can set the card expiration date to any future month and year.
Payments in USD (United States), CAD (Canada), or GBP (the United Kingdom) require a valid postal code.
When testing the SCA flow with one of the European Union test cards, the verification code simulates the SMS verification code sent to the buyer's mobile phone during an actual transaction.
The Sandbox simulates the use of payment cards in Square-supported countries. In production, card brand and country support might be different. Before releasing your application into production, review Supported Payment Methods by Country .
Error state values
You can reproduce certain error states in the Sandbox by providing special values in the Square payment form or In-App Payments SDK.
If you use one of the following values, the nonce returned generates an error when it is processed by the CreatePayment endpoint:
Desired error state | Test values |
---|---|
Card CVV incorrect | CVV: 911 |
Card postal code incorrect | Postal code: 99999 |
Card expiration date incorrect | Expiration date: 01/40 |
Card declined number | Card number: 4000000000000002 |
Card on file auth declined | PAN: 4000000000000010 |
SCA testing in the payment form
To test SCA in the Sandbox, you cannot use a nonce returned by the payment form in the cardNonceResponseReceived event after entering Sandbox credit card numbers or personal credit card numbers. Instead, use a test nonce from the following table.
Use the SqPaymentForm.verifyBuyer function for card present and card on file (CoF) SCA challenges with the following test values:
API call | Parameter | Value | Verification code |
---|---|---|---|
SqPaymentForm.verifyBuyer (present) | source | cnon:card-nonce-requires-verification | 123456 |
SqPaymentForm.verifyBuyer (CoF) | source | ccof:customer-card-id-requires-verification | 123456 |
The SCA flow requires buyers to provide a code sent to the their mobile phone in an SMS message. When testing in the Sandbox, use the verification code to simulate the code sent using SMS.
Important
When testing the SCA flow in the Sandbox, be sure to initialize SqPaymentForm
with a UK location ID.
The SCA flow and these test values are not supported in the legacy Sandbox.
Square API endpoint testing
Test your payments logic that uses the CreatePayment endpoint to take a payment or the CreateCustomerCard endpoint to store a customer card on file.
If you are using the Square Payments API
to generate payments in the Sandbox, you can use one of the Sandbox test nonces as the source_id
in the payment request. You can also use a nonce generated with one of the test payment cards in the Client-side testing section.
API operation | Field | Value |
---|---|---|
Payments.CreatePayment (card) | source_id | cnon:card-nonce-ok |
Payments.CreatePayment (card on file) | source_id | ccof:customer-card-id-ok |
Payments.CreatePayment (Square Gift Card) | source_id | cnon:gift-card-nonce-ok |
Customers.CreateCustomerCard | card_nonce billing_address.postal_code | cnon:card-nonce-ok 94103 |
Note
If you use a Sandbox test nonce in the CreateCustomerCard operation, you must provide 94103 as the postal code in the billing_address
field or the request fails and returns an invalid postal code error.
Generating error states
You can reproduce certain error states in the Square payment endpoint by using the following test values:
Error state | Card present | Card on file |
---|---|---|
Bad CVV | cnon:card-nonce-rejected-cvv | ❌ |
Bad postal code | cnon:card-nonce-rejected-postalcode | ccof:customer-card-id-rejected-postalcode |
Bad expiration date | cnon:card-nonce-rejected-expiration | ccof:customer-card-id-rejected-expiration |
Card declined | cnon:card-nonce-declined | ccof:customer-card-id-declined |
Card nonce already used | cnon:card-nonce-already-used | ❌ |
Gift Card insufficient funds | cnon:gift-card-nonce-insufficient-funds | ❌ |
Gift Card no permissions. | cnon:gift-card-nonce-insufficient-permission | ❌ |
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 | 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 | 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. |
388b5a08-a77c-48ef-ad2a-4a790e6f2789 | Success | Interac credit card payment for the full amount is approved. Only supports CAD amounts. |
2b0b734b-b187-47f0-9d6f-288745210bdb | Success | Interac credit card payment for the full amount is approved, with a 20% tip. Only supports CAD amounts. |
841100b9-ee60-4537-9bcf-e30b2ba5e215 | Failure | 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 | 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 | Checkout 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 checkout times out. |
Example checkout request
This 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 information 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 | 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
Refunds on all other card networks are requested using the Refunds API
Sandbox locations
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 tab for each application in the Developer Dashboard. You can also fetch the location ID programmatically by calling ListLocations with a Sandbox access token.
Sandbox loyalty
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. For more information and other Sandbox values, see Sandbox Test Values.
Sandbox disputes
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 |
Sandbox payment risk evaluation
In sandbox, the following payment amounts in a CreatePayment request generate a Payment
object with risk_evaluation
identifying the specific risk levels.
Charge amount | Risk level |
2222 | MODERATE |
3333 | HIGH |
other values | NORMAL |
Previous
< Test in the SandboxNext
Test with Postman >