A quick reference of test credit card numbers and payment tokens you can use to make test payments with the Square Sandbox.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Sandbox

Sandbox Payments

The Square Sandbox can be used for testing Square API calls. Some of the APIs require special test values when creating transactions in the Sandbox, especially when processing test payments.

Link to section
Overview

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 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.

Important

The Sandbox doesn't accept valid credit cards. You must use test credit card values found in the following sections.

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 don't need to test your client-side payment token logic, use the test payment tokens provided in the Payment tokens for testing the Payments API section to submit payments in the Sandbox.

Link to section
Web and mobile client testing

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.

Link to section
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.

BrandNumberCVV
Visa4111 1111 1111 1111111
Mastercard5105 1051 0510 5100111
Discover6011 0000 0000 0004111
Diners Club3000 000000 0004111
JCB3569 9900 1009 5841111
American Express3400 000000 000091111
China UnionPay6222 9888 1234 0000123
Square Gift Card7783 3200 0000 0000

Note the following:

  • 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.

  • 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.

Link to section
ACH bank transfer success state values

The Sandbox supports ACH bank transfer payments 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.

Link to section
Error state values

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's 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

Link to section
SCA testing in the Web Payments SDK

To test SCA in the Square Sandbox, 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 code
Visa4800 0000 0000 0004111No ChallengeN/A
Mastercard5222 2200 0000 0005111No ChallengeN/A
Discover EU6011 0000 0020 1016111No ChallengeN/A
Visa EU4310 0000 0020 1019111Modal with Verification Code123456
Mastercard5248 4800 0021 0026111Modal with Verification Code123456
Mastercard EU5500 0000 0020 1016111Modal with Verification Code123456
American Express EU3700 000002 010141111Modal with Verification Code123456
Visa4811 1100 0000 0008111No Challenge with Failed VerificationN/A

The SCA flow requires buyers to provide 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 using SMS.

Important

  • With cards that don't have challenges, the card completes the SCA process without the need for a verification window.

  • The Web Payments SDK generates a verification token for each call to verifyBuyer (except when a buyer cancels the SCA challenge). The seller should pass the verification token when it's used to create a payment or store a payment card. The seller should be prepared for situations where Square or the issuer bank might reject the payment or reject storing the payment card. An example of this is the issuer bank determines that the payment request is suspicious and marks it as a fraud transaction or the bank locks the buyer's account.

  • In the Sandbox, verifyBuyer creates a buyer challenge across all regions, mandated or otherwise. In production, you only see a buyer challenge for mandated regions.

The SCA flow and these test values aren't supported in the legacy Sandbox.

Link to section
SCA testing in the In-App Payments SDK

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

Use the BuyerVerification class (Android) or SQIPBuyerVerificationSDK interface (iOS) for card-present and card-on-file (CoF) SCA challenges with the following test values.

BrandNumbersCVVChallenge TypeVerification Code
Visa4800 0000 0000 0012111No ChallengeN/A
Mastercard5222 2200 0000 0013111No ChallengeN/A
Discover EU6011 0000 0020 1024111No ChallengeN/A
Visa EU4310 0000 0020 1027111Modal with Verification Code123456
Mastercard5248 4800 0021 0034111Modal with Verification Code123456
Mastercard EU5500 0000 0020 1024111Modal with Verification Code123456
American Express EU3700 000002 010221111Modal with Verification Code123456
Mastercard5333 3300 0000 0008111Modal with Multi Select Challenge QuestionSelect both Paris and Lyon
Visa4811 1100 0000 0016111No Challenge with Failed VerificationN/A

Link to section
Sandbox payment risk evaluation

In the 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

Link to section
Source IDs for testing the CreatePayment endpoint

In a CreatePayment request, you include the source_id field to provide a payment source to charge. You can use the following test values for testing in the Square Sandbox.

Link to section
Testing a card payment

You can specify either a payment token (representing a card present payment) or an ID of a stored card (representing a card on file payment). Square provides the following test values for both.

  • Payment token values. Use the values in the following table to successfully create a payment:

    Payment field: source_idPayment method
    cnon:card-nonce-okCard
    cnon:gift-card-nonce-okSquare gift card

    In addition, if you want to test errors, use the following test values:

    source_id valueError mapping
    cnon:card-nonce-rejected-cvvBad CVV
    cnon:card-nonce-rejected-postalcodeBad postal code
    cnon:card-nonce-rejected-expirationBad expiration date
    cnon:card-nonce-declinedCard declined
    cnon:card-nonce-already-usedCard payment token already used
    cnon:gift-card-nonce-insufficient-fundsGift card insufficient funds
    cnon:gift-card-nonce-insufficient-permissionGift card no permissions

  • Card on file ID values.

    Payment field: source_idPayment method
    ccof:customer-card-id-okCard on file
    ccof:customer-card-id-requires-verificationCard (SCA)
    ccof:customer-card-id-visa-okVisa card on file
    ccof:customer-card-id-mastercard-okMastercard card on file
    ccof:customer-card-id-american-express-okAmerican Express card on file

    In addition, if you want to test errors, use the following test values.

    source_id valueError mapping
    ccof:customer-card-id-rejected-postalcodeBad postal code
    ccof:customer-card-id-rejected-expirationBad expiration date
    ccof:customer-card-id-declinedCard declined

Link to section
Testing an ACH payment

You can specify either a payment token (representing ACH bank information) or an ID of stored bank on file. Square provides the following test values for both:

  • Payment token values

    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 1 minute.

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

  • Bank account on file ID values

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

Link to section
Testing an Afterpay payment

Use the following test payment tokens as source_id in a CreatePayment request for testing Afterpay payments in the Sandbox:

source_id valueError mappingExpected behavior
wnon:afterpay-or-clearpay-okThe request is successful.
wnon:afterpay-or-clearpay-declinedGENERIC_DECLINEThe request failed.

Link to section
Testing a Cash App payment

Use the following test payment tokens as source_id in a CreatePayment request for testing Cash App payments in the Sandbox:

source_id valueError mappingExpected behavior
wnon:cash-app-okThe request is successful.
wnon:cash-app-declinedGENERIC_DECLINEThe request failed.

Link to section
Source IDs for testing the UpdatePayment endpoint

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 object 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.
On this page