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.
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.
- Testing card-present scenarios is currently not supported.
Test client-side card-not-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.
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 online payments testing.
The Sandbox supports a collection of credit card numbers for all Square-supported card brands for simulating the client side of payment scenarios.
| Brand | Number | CVV |
|---|---|---|
| Visa | 4111 1111 1111 1111 | 111 |
| Mastercard | 5105 1051 0510 5100 | 111 |
| Discover | 6011 0000 0000 0004 | 111 |
| Diners Club | 3000 000000 0004 | 111 |
| JCB | 3569 9900 1009 5841 | 111 |
| American Express | 3400 000000 00009 | 1111 |
| China UnionPay | 6222 9888 1234 0000 | 123 |
| Square Gift Card | 7783 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.
- Payments in Japan do not support postal codes.
- 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.
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.
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 values | Desired error state |
|---|---|
| CVV: 911 | Card CVV incorrect |
| Postal code: 99999 | Card postal code incorrect |
| Expiration date: 01/40 | Card expiration date incorrect |
| Card number: 4000000000000002 | Card declined number |
| PAN: 4000000000000010 | Card on file auth declined |
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-not-present and card-on-file (CoF) SCA challenges with the following test values.
| Brand | Numbers | CVV | Challenge type | Verification code |
|---|---|---|---|---|
| Visa | 4800 0000 0000 0004 | 111 | No Challenge | N/A |
| Mastercard | 5222 2200 0000 0005 | 111 | No Challenge | N/A |
| Discover EU | 6011 0000 0020 1016 | 111 | No Challenge | N/A |
| Visa EU | 4310 0000 0020 1019 | 111 | Modal with Verification Code | 123456 |
| Mastercard | 5248 4800 0021 0026 | 111 | Modal with Verification Code | 123456 |
| Mastercard EU | 5500 0000 0020 1016 | 111 | Modal with Verification Code | 123456 |
| American Express EU | 3700 000002 01014 | 1111 | Modal with Verification Code | 123456 |
| Visa | 4811 1100 0000 0008 | 111 | No Challenge with Failed Verification | N/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,
verifyBuyercreates 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.
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-not-present and card-on-file (CoF) SCA challenges with the following test values.
| Brand | Numbers | CVV | Challenge type | Verification code |
|---|---|---|---|---|
| Visa | 4800 0000 0000 0012 | 111 | No Challenge | N/A |
| Mastercard | 5222 2200 0000 0013 | 111 | No Challenge | N/A |
| Discover EU | 6011 0000 0020 1024 | 111 | No Challenge | N/A |
| Visa EU | 4310 0000 0020 1027 | 111 | Modal with Verification Code | 123456 |
| Mastercard | 5248 4800 0021 0034 | 111 | Modal with Verification Code | 123456 |
| Mastercard EU | 5500 0000 0020 1024 | 111 | Modal with Verification Code | 123456 |
| American Express EU | 3700 000002 01022 | 1111 | Modal with Verification Code | 123456 |
| Mastercard | 5333 3300 0000 0008 | 111 | Modal with Multi Select Challenge Question | Select both Paris and Lyon |
| Visa | 4811 1100 0000 0016 | 111 | No Challenge with Failed Verification | N/A |
In the 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 |
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.
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_id Payment 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 value Error 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_id Payment 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 value Error mapping ccof:customer-card-id-rejected-postalcodeBad postal code ccof:customer-card-id-rejected-expirationBad expiration date ccof:customer-card-id-declinedCard declined
You can specify a payment token which represents ACH bank information. Square provides the following test values:
| source_id value | Error mapping | Expected behavior |
|---|---|---|
bnon:bank-nonce-ok | The request is successful. | |
bnon:bank-nonce-failure | GENERIC_DECLINE | The request failed. |
bnon:bank-nonce-account-unusable | ACCOUNT_UNUSABLE | The request failed. |
bnon:bank-nonce-insufficient-funds | INSUFFICIENT_FUNDS | The request failed. |
bnon:bank-nonce-invalid-account | INVALID_ACCOUNT | The request failed. |
bnon:bank-nonce-buyer-refused-payment | BUYER_REFUSED_PAYMENT | The request failed. |
Note the following:
- The resulting payment has
PENDINGas the initial status, which updates toCOMPLETEDafter 1 minute. - For failed requests, the resulting payment has
PENDINGas the initial status, which updates toFAILEDafter 1 minute.
Use the following test payment tokens as source_id in a CreatePayment request for testing Afterpay payments in the Sandbox:
| source_id value | Error mapping | Expected behavior |
|---|---|---|
wnon:afterpay-or-clearpay-ok | The request is successful. | |
wnon:afterpay-or-clearpay-declined | GENERIC_DECLINE | The request failed. |
Use the following test payment tokens as source_id in a CreatePayment request for testing Cash App payments in the Sandbox:
| source_id value | Error mapping | Expected behavior |
|---|---|---|
wnon:cash-app-ok | The request is successful. | |
wnon:cash-app-declined | GENERIC_DECLINE | The request failed. |
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 mapping | Expected behavior |
|---|---|---|
cnon:card-nonce-ok | The request is successful. | |
cnon:card-edit-not-allowed | BAD_REQUEST | The 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-only | BAD_REQUEST | The 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-failure | AMOUNT_TOO_HIGH | UpdatePayment always returns a tip too high error. |
cnon:card-edit-failure | AMOUNT_TOO_HIGH | UpdatePayment always returns an amount too high error. |
