How to Test Square Payment Processing in Sandbox Mode

What Is Square Sandbox Mode?

Square Sandbox is a free, isolated test environment. It mimics Square's production APIs. You can simulate payments, orders, invoices, and other transactions. No real money is used. No real data is affected. You get a test seller account and test payment methods. The sandbox base URL is https://connect.squareupsandbox.com. Credentials and resources from the sandbox cannot be used in production. The reverse is also true. This separation keeps your live data safe.

Why does this matter? Developers need a safe place to test code. Without a sandbox, you risk charging real customers by mistake. You also risk corrupting your production database. Sandbox mode lets you experiment freely. You can try new features, debug errors, and train your team. All without financial risk.

Prerequisites

Before you start, you need:

• A Square Developer account. It is free to create at developer.squareup.com.
• An application registered in the Square Developer Console. Square provisions a sandbox environment for each application you register.
• Your sandbox API credentials: Application ID and Access Token. You can find these in the Developer Console under your app's credentials section.
• A test seller account. This is automatically created when you register an app.

These prerequisites are simple. Most developers can complete them in under 10 minutes. The sandbox is ready as soon as your app is created.

Step 1: Enable Sandbox Mode in the Developer Console

Log in to the Square Developer Console. Select your application. In the left menu, click Sandbox. Ensure the sandbox toggle is turned on. This activates the sandbox environment for your app. You can also manage test accounts from this page.

Enabling sandbox mode is a one-time setup. Once enabled, all API calls to the sandbox endpoint will use test data. You can toggle it off anytime. But for testing, keep it on.

Step 2: Get Your Sandbox Credentials

In the Developer Console, go to Credentials. Copy your Application ID and Access Token for the sandbox environment. These are different from your production credentials. Use these in your API calls to authenticate against the sandbox endpoint.

Why separate credentials? Security. If you accidentally expose your production token, someone could charge real cards. Sandbox tokens are harmless. They only work in the sandbox. Store them safely anyway. Treat them like real secrets in your code.

Step 3: Use the Correct Sandbox Endpoint

All API calls must go to the sandbox base URL: https://connect.squareupsandbox.com. For example, to create a payment, use https://connect.squareupsandbox.com/v2/payments. For OAuth, use https://connect.squareupsandbox.com/oauth2/token. Never use the production URL (https://connect.squareup.com) during sandbox testing.

This is a common mistake. Developers copy code from production and forget to change the URL. The result is a failed request or, worse, a real charge. Always double-check your endpoint. Use environment variables to store the base URL. That way, you can switch between sandbox and production with a single config change.

Step 4: Choose a Test Payment Method

Square provides test credit card numbers that return predictable results. You can use these to generate one-time-use payment tokens via the Web Payments SDK or In-App Payments SDK. Alternatively, you can use test source IDs directly in the CreatePayment API call. The sandbox does not accept real credit cards.

Test Credit Card Numbers

Use any future expiration date (e.g., 12/25) and any 5-digit ZIP code (e.g., 94103). These test numbers are documented by Square. They never change. You can rely on them for consistent testing.

Step 5: Make a Test Payment API Call

Here is an example using cURL to create a payment of $10.00 (1000 cents) with a test source ID. Replace YOUR_ACCESS_TOKEN with your sandbox access token.

curl -X POST https://connect.squareupsandbox.com/v2/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "source_id": "cnon:card-nonce-ok",
    "idempotency_key": "unique-key-123",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    }
  }'

The source_id value cnon:card-nonce-ok is a test nonce that always succeeds. For a declined payment, use cnon:card-nonce-declined. The idempotency_key must be unique for each request to prevent duplicate charges.

Why use an idempotency key? Network errors can cause retries. Without a unique key, the same payment might be processed twice. The key ensures each request is processed only once. Generate a new UUID for every payment attempt.

Step 6: Verify the Payment in the Sandbox Dashboard

After a successful API call, log in to the Sandbox Square Dashboard (accessible from the Developer Console). Go to Transactions or Payments. You should see the test payment listed with the amount and status. This confirms the payment was processed correctly in the sandbox.

Verification is crucial. It confirms your integration works end-to-end. Check the status, amount, and currency. Also check the card brand and last four digits. If something looks wrong, debug your API call. The sandbox dashboard gives you full visibility.

Common Mistakes and How to Avoid Them

• Using production credentials in sandbox calls. Always double-check that your access token and application ID are from the sandbox environment.
• Using the production base URL. Ensure all API endpoints start with https://connect.squareupsandbox.com.
• Using a real credit card. The sandbox only accepts test card numbers. Real cards will be rejected.
• Not using a unique idempotency key. Reusing the same key for different requests can cause unexpected results.

These mistakes are easy to make. They are also easy to fix. Use environment variables. Write unit tests that check your endpoint URL. Always use test cards. Generate fresh idempotency keys. A little discipline saves hours of debugging.

Limitations of Square Sandbox

The sandbox does not support card-present (in-person) testing. It only simulates card-not-present transactions (online payments). Also, the sandbox does not process real payments, so you cannot test refunds to real cards. Some advanced features like chargebacks or disputes may not be fully simulated. For a complete list, refer to Square's sandbox documentation.

These limitations matter for planning. If your app uses Square Reader or Terminal, you need a different test approach. Square provides a separate test environment for in-person payments. Check their docs. Also, sandbox performance may differ from production. Do not use sandbox for load testing. It is not designed for high volume.

Frequently Asked Questions

Can I test recurring payments in sandbox mode?

Yes. You can create a card on file using test card numbers and then use that card for recurring charges. Use the CreateCard API with a test nonce, then call CreatePayment with the card ID.

How do I test declined payments?

Use a test card with CVV 222 or the test nonce cnon:card-nonce-declined. This will return a declined response from the sandbox.

Does sandbox mode cost anything?

No. Square Sandbox is free to use. You do not need a paid Square account to access it.

Can I test webhooks in sandbox mode?

Yes. You can configure webhook URLs in the Developer Console for your sandbox app. The sandbox will send webhook events for test transactions, allowing you to verify your webhook handler.

How do I reset my sandbox data?

You can reset your sandbox test account from the Developer Console. This clears all test transactions and data. You can also create multiple test accounts if needed.

What is the difference between sandbox and production?

Sandbox uses test data and fake payments. Production uses real data and real money. Credentials, endpoints, and accounts are completely separate. You cannot mix them.

Can I test Square APIs other than payments in sandbox?

Yes. The sandbox supports many Square APIs, including Orders, Catalog, Customers, and Invoices. Each API has its own test values and walkthroughs.

How do I test different currencies?

Set the currency field in your API request. The sandbox supports multiple currencies. Use USD, CAD, GBP, JPY, and others. The sandbox will process the payment in that currency. No real conversion happens.

Can I simulate a partial refund?

Yes. Use the RefundPayment API with a test payment ID. The sandbox will process the refund. You can refund the full amount or a partial amount. Check the sandbox dashboard to verify.

What happens if I exceed rate limits?

The sandbox has rate limits similar to production. If you exceed them, you get a 429 response. Wait and retry. This helps you test your rate limit handling code.