Square Test Card: Sandbox Payment Testing Guide

What a Square test card is

A Square test card is a card number that the Square sandbox accepts for payment testing. It never reaches a real issuer, moves no money, and exists so you can run charges, refunds, and decline scenarios before you accept live payments. Square publishes a table of test numbers by card brand in its developer documentation. Use those numbers only with sandbox credentials. A test card sent to the production endpoint will fail or, worse, create a real payment record you have to void.

Prerequisites

• A Square developer account with at least one application
• The sandbox application ID and sandbox access token for that application
• A sandbox location ID
• A test client: the Web Payments SDK sample, the In-App Payments SDK, or the API Explorer

How to run a test charge

1. Sign in to the Developer Dashboard and set the application toggle to Sandbox.
2. Copy the sandbox application ID into your checkout configuration.
3. Copy the sandbox access token into your server environment variables.
4. Load your checkout page with the Web Payments SDK initialized in sandbox mode.
5. Enter a test number from the published table, such as 4111 1111 1111 1111 for Visa.
6. Enter a future expiration date and the CVV that the documentation lists for that card.
7. Submit the payment and confirm the API response returns a payment ID with an APPROVED status.
8. Open the Sandbox section of the Dashboard and confirm the payment appears in the transaction list.
9. Send a refund request against that payment ID and confirm the refund object comes back with a matching amount.

Testing declines and error paths

Happy-path charges prove little on their own. Square also lists test cards and CVV values that trigger specific failures, including card declines and CVV mismatches. Wire each one into an automated test so your checkout shows the right message instead of a blank error screen. Keep a separate case for network timeouts and for duplicate idempotency keys, since those are the failures that cost real merchants money.

Common mistakes

• Mixing a sandbox application ID with a production access token, which returns an authentication error
• Hardcoding a test number in a build that later ships to production
• Assuming the published table is fixed; Square updates the numbers and the sandbox behavior over time
• Skipping the refund and void tests because the charge itself succeeded

Keeping test data separate

Gate every test card and sandbox key behind an environment flag, and fail the build if a sandbox token appears in a release configuration. Store card data only inside the SDK's hosted fields so your servers never touch a full number, which keeps you inside PCI DSS scope limits. Review the current Square test card table before each integration release, because a number that worked last quarter may now return a different result.