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.
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.
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.
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.
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-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,
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.
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.
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-ok
Card cnon:gift-card-nonce-ok
Square gift card In addition, if you want to test errors, use the following test values:
source_id value Error mapping cnon:card-nonce-rejected-cvv
Bad CVV cnon:card-nonce-rejected-postalcode
Bad postal code cnon:card-nonce-rejected-expiration
Bad expiration date cnon:card-nonce-declined
Card declined cnon:card-nonce-already-used
Card payment token already used cnon:gift-card-nonce-insufficient-funds
Gift card insufficient funds cnon:gift-card-nonce-insufficient-permission
Gift card no permissions Card on file ID values.
Payment field: source_id
Payment method ccof:customer-card-id-ok
Card on file ccof:customer-card-id-requires-verification
Card (SCA) ccof:customer-card-id-visa-ok
Visa card on file ccof:customer-card-id-mastercard-ok
Mastercard card on file ccof:customer-card-id-american-express-ok
American 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-postalcode
Bad postal code ccof:customer-card-id-rejected-expiration
Bad expiration date ccof:customer-card-id-declined
Card declined
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 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 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 value Error mapping Expected behavior bact:customer-bank-account-id-ok
The request is successful. bact:customer-bank-account-id-failure
GENERIC_DECLINE The request failed. bact:customer-bank-account-id-account-unusable
ACCOUNT_UNUSABLE The request failed. bact:customer-bank-account-id-insufficient-funds
INSUFFICIENT_FUNDS The request failed. bact:customer-bank-account-id-invalid-account
INVALID_ACCOUNT The request failed. bact:customer-bank-account-id-buyer-refused-payment
BUYER_REFUSED_PAYMENT The request failed.
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. |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.