Sandbox Test Values
Test Square API operations in the v2 Sandbox.
On this page
Sandbox test values are used to test the client and server sides of payment processing in the Square v2 Sandbox.
For information about test values for the deprecated legacy Sandbox, see Legacy Sandbox Test Values.
Square platform clients such as the payment form and In-app Payment apps 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 v2 Sandbox.
Test client-side card-present logic in your payment form or In-App Payment app 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.
You can use test credit cards with the payment form and In-AppPayments SDK to input card numbers that will generate a testable payment nonce.
The sandbox supports a collection of credit card numbers for all Square-supported card brands for simulating the client-side of payment scenarios.
|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 0000 0000 04||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||❌|
You can set the card expiration date to any future month and year.
Payments in USD (United States), CAD (Canada), or GBP (United Kingdom) also 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 mobile phone during an actual transaction.
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 will trigger 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|
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:
The SCA flow requires that the buyer provides a code sent to their mobile phone in an SMS message. When testing in the sandbox use the Verification Code to simulate the code sent via SMS.
When testing the SCA flow in v2 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.
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.
Note: You can also use a nonce generated with one of the test payment cards from the Client-side testing section.
Sandbox test nonces
(card on file)
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 will fail and return an with an invalid postal code error.
You can reproduce certain error states in the Square payment and card on file endpoints by using the following test values.
|Error state||CreatePayment endpoint||CreateCustomerCard endpoint|
|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 nonce already used||cnon:card-nonce-rejected-cvv||N/A|
Your sandbox account comes with 1 mock location per application. This location is unrelated to the production locations listed in the Square Dashboard
The sandbox location ID for a given application is listed on the Locations tab of the application control panel in the Application Dashboard. You can also fetch the location ID programmatically by calling ListLocations with a sandbox access token.
Use these predefined payment amounts that map to a specific dispute reason. 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|