Testing

Sandbox Test Values

Test Square API operations in the Square Sandbox using test values.

Sandbox test values are used to test the client and server sides of payment processing in the Square Sandbox.

Sandbox payments Permalink Get a link to this section

Square platform clients, such as Web Payments SDK and In-App Payments SDK applications, accept payment cards and return one-time use encrypted payment tokens (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 Web Payments SDK or In-App Payments SDK application by using test credit card numbers to generate payment tokens 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 payment token logic, use the test payment tokens provided in the Square endpoint testing section to submit payments in the Sandbox.

Web and mobile client testing Permalink Get a link to this section

You can use Sandbox credit cards with the Web Payments SDK and In-App Payments SDK to input card numbers that generate a payment token for Sandbox testing.

Card present success state values Permalink Get a link to this section

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
NumberCVVVerification Code
Visa4111 1111 1111 1111111
Visa EU4310 0000 0020 1019111123456
MasterCard5105 1051 0510 5100111
MasterCard EU5500 0000 0020 1016111123456
Discover6011 0000 0000 0004111
Discover EU6011 0000 0020 1016111123456
Diners Club3000 000000 0004111
JCB3569 9900 1009 5841111
American Express3400 000000 000091111
American Express EU3700 000002 010141111123456
China UnionPay6222 9888 1234 0000123
Square Gift Card7783 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 (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.

ACH Bank Transfer success state values Permalink Get a link to this section

The Sandbox supports ACH Bank Transfer by accepting the test user name user_good and the test password pass_good. These test values are provided by the Plaid API and might change in the future. For more information, see the Plaid Sandbox test credentials page.

Error state values Permalink Get a link to this section

You can reproduce certain error states in the Sandbox by providing special values in the Web Payments SDK or In-App Payments SDK.

If you use one of the following values, the returned payment token generates an error when it is processed by the CreatePayment endpoint:

Test valuesDesired error state
CVV: 911Card CVV incorrect
Postal code: 99999Card postal code incorrect
Expiration date: 01/40Card expiration date incorrect
Card number: 4000000000000002Card declined number
PAN: 4000000000000010Card on file auth declined

SCA testing in Web Payments SDK Permalink Get a link to this section

To test SCA in the Sandbox environment, you should use a payment token returned by the Web Payments SDK. To test different SCA scenarios, use the cards provided in the following table.

Use the Payments.verifyBuyer function for card present and card on file (CoF) SCA challenges with the following test values:

Brand
Numbers
CVVChallenge typeVerification codeWorks for
Mastercard5248 4800 0021 0026111Modal with Verification Code123456All Accounts
Visa EU4310 0000 0020 1019111Modal with Verification Code123456UK Accounts Only
Visa4800 0000 0000 0004111FrictionlessN/AAll Accounts
Visa4811 1100 0000 0008111Failed VerificationN/AAll Accounts
Mastercard EU5500 0000 0020 1016111Modal with Verification Code123456UK Accounts Only
Mastercard5222 2200 0000 0005111FrictionlessN/AAll Accounts
Mastercard5333 3300 0000 0008111Modal with Multiple Verification QuestionsChallenge 1: Thomason
Challenge 2: Select both St Louis & Dallas
Challenge 3. Smith
All Accounts
American Express EU3700 000002 01014111Modal with Verification Code123456UK Accounts Only

Note

To test a card on file, use the Visa EU number.

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 Payments.setLocale with a UK location ID.

  • With frictionless challenges, the card completes the SCA process without the need for a verification modal.

  • A failed verification challenge does not provide a verification token. In this case, the error parameter in the verifyBuyer callback contains an error message.

The SCA flow and these test values are not supported in the legacy Sandbox.

Payments API endpoint testing Permalink Get a link to this section

Test your payments logic that uses the CreatePayment endpoint to take a payment or the CreateCard endpoint to store a customer's 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 payment tokens as the source_id in the payment request.

Payments API Permalink Get a link to this section

Use the values in the following table with calls to the CreatePayment endpoint that succeed in creating a payment.

Payment field: source_idPayment method
cnon:card-nonce-okCard
ccof:customer-card-id-okCard on file
cnon:gift-card-nonce-okSquare gift card
ccof:customer-card-id-requires-verificationCard (SCA)

In addition, if you want to test errors in the Square CreatePayment endpoint, you can use the following test values:

source_id valueError mapping
Card present. cnon:card-nonce-rejected-cvvBad CVV
Card present. cnon:card-nonce-rejected-postalcode
Card on file. ccof:customer-card-id-rejected-postalcode
Bad postal code
Card present. cnon:card-nonce-rejected-expiration
Card on file. ccof:customer-card-id-rejected-expiration
Bad expiration date
Card present. cnon:card-nonce-declined
Card on file. ccof:customer-card-id-declined
Card declined
Card present. cnon:card-nonce-already-usedCard nonce already used
Card present. cnon:gift-card-nonce-insufficient-fundsGift card insufficient funds
Card present. cnon:gift-card-nonce-insufficient-permissionGift card no permissions

Payment tokens for ACH Bank Transfer payments Permalink Get a link to this section

source_id valueError mappingExpected behavior
bnon:bank-nonce-okThe request is successful.
bnon:bank-nonce-failureGENERIC_DECLINEThe request failed.
bnon:bank-nonce-account-unusableACCOUNT_UNUSABLEThe request failed.
bnon:bank-nonce-insufficient-fundsINSUFFICIENT_FUNDSThe request failed.
bnon:bank-nonce-invalid-accountINVALID_ACCOUNTThe request failed.
bnon:bank-nonce-buyer-refused-paymentBUYER_REFUSED_PAYMENTThe request failed.

Note the following:

  • The resulting payment has PENDING as the initial status, which updates to COMPLETED after one minute.

  • For failed requests, The resulting payment has PENDING as the initial status, which updates to FAILED after one minute.

PAYMENT TOKENS FOR TESTING UPDATE PAYMENT REQUESTS Permalink Get a link to this section

You can also use the following test values to create payments using CreatePayment. The benefit of using these token values is that updates to these payments using UpdatePayment always return the following predictable results.

source_id value
Error mappingExpected behavior
cnon:card-nonce-okThe request is successful.
cnon:card-edit-not-allowedBAD_REQUESTThe Payment created using this token has no capabilities. As a result, any UpdatePayment request to update the amount or tip fails.
cnon:card-edit-down-onlyBAD_REQUESTThe Payment created using this token has EDIT_AMOUNT_DOWN and EDIT_TIP_AMOUNT_DOWN capabilities. An UpdatePayment request that reduces these amounts succeeds. However, any attempt to increase these amounts fails.
cnon:card-edit-tip-failureAMOUNT_TOO_HIGHUpdatePayment always returns a tip too high error.
cnon:card-edit-failureAMOUNT_TOO_HIGHUpdatePayment always returns an amount too high error.

Cards API Permalink Get a link to this section

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 that are used with calls to CreateCard and successfully create a card on file for a customer.

FieldValue
card_noncecnon:card-nonce-ok
billing_address.postal_code94103

Note

If you use a Sandbox test payment token with the CreateCard or CreateCustomerCard (deprecated) 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.

Terminal API - checkouts Permalink Get a link to this section

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 Permalink Get a link to this section

Device ID
Result
Details
9fa747a2-25ff-48ee-b078-04381f7c828fSuccessThe 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-67f0c26346b0SuccessThe 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-4a790e6f2789SuccessThe Interac credit card payment for the full amount is approved. Only supports CAD amounts.
2b0b734b-b187-47f0-9d6f-288745210bdbSuccessThe Interac credit card payment for the full amount is approved, with a 20% tip. Only supports CAD amounts.
19a01fbd-3dcd-4d9f-a499-a641684af745SuccessThe eMoney/FeLiCa credit card payment for the full amount is approved, with a 20% tip.
841100b9-ee60-4537-9bcf-e30b2ba5e215FailureThe 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-8eac603ffc5eFailureThe 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-f42e36dab0c7FailureThe 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 Permalink Get a link to this section

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 Permalink Get a link to this section

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 Permalink Get a link to this section

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-ec3fb8d33291SuccessComplete 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-b2fbb672e712FailureThe 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-f8de0e864242FailureThe 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-513644de434dFailureThe 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 Permalink Get a link to this section

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 Permalink Get a link to this section

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.

Sandbox disputes Permalink Get a link to this section

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 amountDispute reason
8801AMOUNT_DIFFERS
8802CANCELLED
8803DUPLICATE
8804NO_KNOWLEDGE
8805NOT_AS_DESCRIBED
8806NOT_RECEIVED
8807PAID_BY_OTHER_MEANS
8808CUSTOMER_REQUESTS_CREDIT
8809EMV_LIABILITY_SHIFT

Sandbox payment risk evaluation Permalink Get a link to this section

In Sandbox, the following payment amounts in a CreatePayment request generate a Payment object with risk_evaluation identifying the specific risk levels.

Charge amountRisk level
2222MODERATE
3333HIGH
other valuesNORMAL

Previous

< Test in the Sandbox

Next

Test with Postman >