Documentation Manage Apps

Testing using the API sandbox

Connect API v2 provides a sandbox that lets you test out API endpoints in a non-production environment. Transactions created in the sandbox are not sent through to card networks, and cards are never charged.

You use the sandbox by providing a special sandbox access token instead of a normal access token when sending requests to the API.

Sandbox endpoints are not currently available for Connect v1, or for the Register API.

Obtaining a sandbox access token

Every Connect API application has a sandbox application ID and sandbox access token assigned to it. These credentials are available alongside your application's standard credentials in the application dashboard. Click the application you want sandbox credentials for, then refer to the Sandbox section at the bottom.

Like your personal access token, your sandbox access token is a secure credential. If you think your sandbox access token has been compromised, you can replace it by clicking Replace Token in the Sandbox Access Token field.

Note: You cannot generate sandbox access tokens with the OAuth API. You must use the sandbox access token listed on the application dashboard for testing.

Generating a sandbox card nonce

As described in Embedding the payment form, you provide your application ID to the SqPaymentForm when you initialize it. To generate a payment form that produces sandbox card nonces, provide your sandbox application ID to the SqPaymentForm instead. If you do, all nonces generated by the payment form will work only for sandbox-specific requests.

Sending sandbox-specific requests

Sandbox API requests are different from standard API requests in just a couple ways: the access token you use and the locations you interact with.

Providing a sandbox access token

Provide your sandbox access token exactly how you provide any other access token: in the Authorization header of your request, with the following format:

Authorization: Bearer SANDBOX_ACCESS_TOKEN

Working with sandbox locations

Your sandbox account comes with a collection of mock locations. These locations are totally distinct from your actual Square account's locations.

You can fetch the IDs for your sandbox locations with a request to the ListLocations endpoint. Be sure to provide your sandbox access token as explained in Providing a sandbox access token.

Sandbox special values

The sandbox supports a collection of special values you can use to simulate various scenarios when charging a card.

Card brands

When generating a sandbox card nonce with the SqPaymentForm, you can use these card numbers to simulate cards of particular brands:

Brand Number
Visa 4532759734545858
MasterCard 5409889944179029
Discover 6011033621379697
Diners Club 36004244846408
JCB 3566005734880650
American Express 371263462726550
China UnionPay 6222520119138184

You can provide any CVV, expiration date, and postal code with these card numbers (except for those listed in Generating error states, provided the values are logically correct (for example, the expiration date must be in the future).

Generating error states

You can reproduce certain error states in the sandbox by providing special values in the payment form or directly to the Charge endpoint.

If you provide one of the following values when generating a nonce with the payment form, the nonce you receive will generate the error indicated when provided to the Charge endpoint:

Error state To reproduce
Card CVV incorrect Specify 911 as the CVV in the payment form.
Card postal code incorrect Specify 99999 as the postal code in the payment form.
Card expiration date incorrect Specify 01 as the expiration month and 40 as the expiration year in the payment form.
Card declined Specify 403 in the amount_money field of your request to the Charge endpoint.

If you don't want to generate a nonce with the payment form, you can also generate errors by providing the following values in the card_nonce or customer_card_id fields of a request to the Charge endpoint.

Error state card_nonce customer_card_id
None (transaction succeeded) fake-card-nonce-ok fake-customer-card-id-ok
Card CVV incorrect fake-card-nonce-rejected-cvv fake-customer-card-id-rejected-cvv
Card postal code incorrect fake-card-nonce-rejected-postalcode fake-customer-card-id-rejected-postalcode
Card expiration date incorrect fake-card-nonce-rejected-expiration fake-customer-card-id-rejected-expiration
Card declined fake-card-nonce-declined fake-customer-card-id-declined
Card nonce already used fake-card-nonce-already-used N/A