Learn how to get started and make a Square API request.
Get Started

Step 2: Make an API Request

Now that you have created a Square account (see Get Started), you can explore API calls. You use the following to test a Square API request and review the response:

  • Square Sandbox. An isolated test environment.

  • API Explorer. An interactive tool you can use to send HTTP requests to Square. In this topic, you send HTTP requests to the Square Sandbox.

  • API Logs. An interactive tool you can use to view V2 API logs to test and debug applications, troubleshoot API issues, and get a real-time view of activity across integrations.

Before you deploy your own solutions to production, you can use these tools and environments to test APIs.

When you created your Square account, Square created a Merchant object and a Location object. You can use the Merchants API and Locations API to review these details.

  1. Get the Sandbox access token. The application you created in the preceding step provides you with the necessary credentials for Sandbox testing.

    1. Sign in to the Developer Dashboard.

    2. Choose the application.

    3. At the top of the page, choose Sandbox.

    4. In the Sandbox Access Token box, choose Show, and then copy and save the Sandbox access token.

  2. Call the Merchants API to get the account information:

    1. Open API Explorer.

    2. From the drop-down lists, choose Merchants and List merchants.

    3. Note that API Explorer, by default, uses the Sandbox domain (connect.squareupsandbox.com) in the endpoint URL.

    4. Paste the copied Sandbox access token into the Access token box. Note that API Explorer provides two options:

      • You enter the Sandbox access token.

      • API Explorer gives you the option to sign in to your Square account. API Explorer then retrieves the application information and shows the available access tokens in a drop-down list.

    5. Choose Run Request.

    6. Review both the cURL Request and Response in API Explorer.

      Note

      If your account is created in an unsupported region (where Square cannot process payments), the response shows that the Sandbox test account is created in the US. As mentioned earlier in About the Square Sandbox, a Sandbox test account can only be created in regions where Square can process payments.

  3. Call the Locations API to access the Location object that Square created for the account:

    1. In API Explorer, choose Locations and List locations from the drop-down lists.

    2. Note that API Explorer, by default, uses the Sandbox domain (connect.squareupsandbox.com) in the endpoint URL.

    3. Provide the Sandbox access token.

    4. Choose Run Request.

    5. Review both the cURL Request and Response in API Explorer.

      • If you created your Square account in a region where Square can process payments, the response shows a preconfigured address for that region.

      • If you created your Square account in an unsupported region (where Square cannot process payments), the Location object does not have an address.

You can now test an API call. For example, you make a Payments API call (CreatePayment endpoint).

An animation showing how to use API Explorer to make a test Payments API call using the CreatePayment endpoint.

To take a payment, the following information is required:

  • Payment source. One of the payment sources that the API supports is a payment token (a secure token that represents a payment source such a credit card). When you integrate Square payments in your web or mobile applications, the libraries you use generate a payment token from the card information. You then use the server-side Payments API to charge the payment token. For now, do not worry about generating a payment token. Square provides test payment tokens (cnon:card-nonce-ok) for Sandbox use. For more information, see Take Payments.

  • Amount details. This includes the amount and currency. You specify the currency that is valid for the region in which you created your Square account.

  • Authorization information. You use the Sandbox access token to authorize the request. This access token has full permissions so you can make the Payments API call.

Follow these steps to make a CreatePayment call:

  1. In API Explorer, choose the API (Payments) and endpoint (CreatePayment) from the drop-down lists.

  2. In the Access token box, enter your Sandbox access token.

  3. Provide the following required request Body fields:

    • amount_money. Provide both the amount and currency field values. The amount is the smallest denomination of the currency. For example, when the currency is USD, the amount is in cents.

    • Idempotency_key. Provide a unique key or choose Generate.

    • source_id. Choose the fake payment token (cnon:card-nonce-ok) provided for Sandbox testing.

  4. Choose Run Request.

  5. Review the following:

    • Request. It is the cURL command that created the payment.

    • Response. It shows the Payment object created with the status of COMPLETED.

The Square account you created provides a default Sandbox test account. The test account provides an isolated environment that includes a test service (that mirrors the production environment in functionality), data storage for test data, and the Sandbox Seller Dashboard (separate from the production Seller Dashboard). When you make API calls using the Sandbox test account, you can verify those transactions in the associated Sandbox Seller Dashboard. These transactions do not affect your production data.

Open the Developer Dashboard and review the Applications page, as shown in the following example:

An animation showing how to preview details of the default Sandbox test account and the associated Sandbox Seller Dashboard.

The Sandbox Test Accounts section shows the Default Test Account.

  1. Review the Sandbox default test account:

    1. Choose (ellipsis) and view the details of the Sandbox default test account.

      Note

      If you created your Square account in a supported region (where Square supports processing payments, see supported countries), Square creates this Sandbox default test account in the same country as your Square account. Otherwise, Square creates the account in the US because the Sandbox test account can only be created in regions where Square can process payments.

    2. Choose Done to close the Account Details window.

  2. Review the Seller Dashboard provided for the Sandbox default test account. Choose Open next to Default Test Account. It is similar to the production Seller Dashboard as explained in Step 1: Create an account and application.

  3. Review and close the Sandbox Seller Dashboard.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.