Testing

Sandbox Support

Learn about Square API sandbox support.

Testing with sandbox

Square provides limited sandbox support for key Connect v2 API endpoints. The sandbox lets you test integrations with payment APIs in a non-production environment. The sandbox does not send payment requests to the credit card networks so payment API will never charge credit cards.

Sandbox support is available for

Sandbox limitations

  • Sandbox transactions are not logged and do not appear in the Dashboard.
  • Customers created with sandbox credentials do not appear in the Dashboard and cannot be accessed with production API calls
  • Sandbox support is not available for mobile APIs and SDKs.
  • Sandbox support is not available for digital wallets with the Square Payment Form.
  • Sandbox support is not available for multiparty transaction functionality in the Transactions API.
  • Sandbox support is not available for the following APIs:
  • ApplePay API
  • Reporting API
  • Catalog API
  • OAuth API
  • All Connect v1 APIs

For end-to-end testing or to test unsupported APIs and SDKs, we recommend using production credentials for an activated Square account that is approved for payments.

Using the sandbox

Every application has a sandbox application ID, a sandbox access token, and a set of sandbox location IDs. These credentials are available on the Credentials tab of the application control panel in the Application Dashboard.

To find your sandbox credentials and sandbox location IDs:

  1. Go to the Application Dashboard.
  2. Click on your application to open the application control panel.
  3. Click on the Credentials tab to find your sandbox token.
  4. To find your sandbox location IDs, click the Locations tab or call the ListLocations endpoint with your sandbox credentials.

Your sandbox access token is a secure credential. If you think your sandbox token has been compromised, click Replace Token in the Sandbox Access Token field to generate a new sandbox token.

Using the sandbox with the Square Payment Form

You provide your application ID to the SqPaymentForm when you initialize it. To generate a payment form that produces sandbox card nonces, make sure to use your sandbox application ID to initialize SqPaymentForm. Sandbox nonces generated by SqPaymentForm only work for sandbox API requests.

Try it out!

Now that you have a sandbox token, use the tool below to send a test payment.

To send a Charge request, we first need to get a location_id from the ListLocations endpoint.

  1. Paste your sandbox token in the Sandbox Token field.
  2. Select "Locations" from the API dropdown.
  3. Select "ListLocations" from the Endpoint dropdown.
  4. Click Send Request and the response body will appear as JSON under Response.

To send a Charge request, update the JSON block in the Request text area:

  1. Pick a location_id from the response for a location that accepts credit cards and copy it.
  2. Select Transactions from the API dropdown.
  3. Select Charge from the Endpoint dropdown.
  4. Paste the location_id you saved in the location_id field.
  5. Update the example request:
    1. Set idempotency_key to any unique string (you'll need to update this string for each new Charge request).
    2. Set card_nonce to one of the following sandbox nonce values:
      • fake-card-nonce-ok — returns a successful test transaction.
      • fake-card-nonce-declined — returns a "Card Declined" error.
  6. Click Send Request and the response body will appear as JSON under Response.
Alert
Alert
Alert
Alert
Alert
Alert
Request
{
  "idempotency_key": "",
  "card_nonce": "",
  "reference_id": "RPCE#12345 ",
  "note": "Miscellanious dog toys",
  "delay_capture": false,
  "shipping_address": {
    "address_line_1": "123 Main St",
    "locality": "San Francisco",
    "administrative_district_level_1": "CA",
    "postal_code": "94114",
    "country": "US"
  },
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "NY",
    "locality": "New York",
    "postal_code": "10003",
    "country": "US"
  },
  "amount_money": {
    "amount": 5000,
    "currency": "USD"
  }
}
This endpoint does not require a request body
Response Alert

  

The widget above also supports the Customers API and Checkout API! Visit the Connect v2 API Reference and try running the example requests in the widget.

Prev
< Testing
Next
Testing Square APIs with Postman >

Ask for help on Stack Overflow or join our Slack channel