Build with Square

Get Started

Square provides collections of APIs that work together to solve a variety of problems. Developers can build solutions using the Square platform to meet the business needs of Square sellers. This topic walks you through signing up for a Square account and testing Square APIs using the API Explorer tool and the Sandbox test environment.

Step 1: Sign up for a Square account Permalink Get a link to this section

To work with Square APIs, developers must first create a Square account. To create a account, go to the Let's create your account page and enter the required information.

When you sign up for a Square account, Square provides two dashboards:

  • Developer Dashboard. Use the Developer Dashboard to create and manage your applications, access the Sandbox Seller Dashboard, configure webhooks for real-time notifications, and perform other development tasks.

  • Seller Dashboard. The Seller Dashboard provides sellers with tools to manage daily business operations. A seller can control just about everything needed to ensure that the business is running smoothly.

    In addition, there is a Sandbox Seller Dashboard for developers to use when testing APIs in the Square Sandbox. Developers access it through the Developer Dashboard. For more information, see Square Dashboard.

Step 2: Create an application Permalink Get a link to this section

A developer must have an application in the Developer Dashboard.

A Square application enables external applications/solutions to connect to Square. An application can span a variety of use cases. In addition to managing credentials, you can manage webhook subscriptions, API versions, Apple Pay configuration, and so on. The API version defined in the application is the default Square API version. If an incoming request does not include an API version, the default is used.

You can create additional applications. Consider these examples:

  • You use the Square platform to create a web solution and a mobile solution. In this case, you might choose to create separate applications in your account.

  • You create independent solutions to manage different scenarios, such as manage orders and manage teams.

Follow these steps to create an application:

  1. Sign in to the Developer Dashboard using your user name and password, and then create your first application by providing a name.

  2. On the Applications page, choose Open for the application you created.

  3. On the left navigation pane, choose the following pages and review the application configuration settings:

    1. Credentials. Provides credentials you can use to authenticate requests. Separate credentials are provided for use in production and Sandbox testing. The API version identifies the version used in your solution. If an API request includes a version, it takes precedence. If the request does not include an API version, the version in the application configuration is used.

      Note

      This access token has permissions to perform all Square API actions. You should not share the access token with others.

    2. Locations. Displays the location ID for your Square account. Square creates the initial location ID based on information you provided during signup. Several Square APIs require your location ID. Therefore, in addition to the Seller Dashboard, the Developer Dashboard provides this information for convenience.

    3. OAuth. Enables management of the OAuth workflow for your custom solutions.

get-started-2.CreateApp

In addition, the application maintains other information, such as a Webhooks page (for real-time notifications) and other API configurations. This topic does not go into details but provides links to relevant topics at the end.

Step 3: Make an API request Permalink Get a link to this section

You use the following to make and review a Square API request:

  • 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 (beta). 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.

About the Square Sandbox Permalink Get a link to this section

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), 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.

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

  2. The Sandbox Test Accounts section shows the Default Test Account.

    1. Choose (ellipsis) and view the account details. Square creates this default test account in the same country as your Square account.

    2. Choose Done to close Account Details.

    3. Click Open next to Default Test Account to open the Sandbox Seller Dashboard that Square provided with the test account. It is similar to the production Seller Dashboard as explained in Step 1. Review and close the Sandbox Seller Dashboard.

get-started-3a.MakeAPIRequest

Make a test API call Permalink Get a link to this section

You can now test an API call. For illustration, you make a Payments API call (CreatePayment endpoint). To take a payment, the following information is required:

  • Payment source. One of the payment sources that the API supports is a nonce (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 nonce from the card information. You then use the server-side Payments API to charge the nonce. For now, do not worry about generating a nonce. Square provides a test nonce (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 the API call:

  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 using your user name and password, and then create your first application.

    2. Choose the application.

    3. Choose Sandbox at the top of the page.

    4. Copy the Sandbox Access Token.

  2. (optional) Find the currency for your Square account. If you do not know the currency, call the Merchants API to get the account information:

    1. Open API Explorer at https://developer.squareup.com/explorer/square.

    2. Choose Merchants and List merchants from the drop-down menus.

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

    4. Provide the Sandbox Access token. 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 menu.

    5. Choose Run Request to submit the request.

    6. Review both the cURL Request and Response in the API Explorer UI. Note the currency value.

  3. Send a CreatePayment request to take a payment.

    1. In API Explorer, choose the API (Payments) and endpoint (Create Payment) from the drop-down menus.

    2. Provide the Access token. It is 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 currency is USD, amount is in cents.

      • Idempotency_key. Provide a unique key or choose Generate.

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

    4. Choose Run Request to send the request.

    5. Review the following:

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

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

get-started-3b.MakeAPIRequest

Step 4: View the transaction in the API Logs (beta) Permalink Get a link to this section

You can view the API logs in the Developer Dashboard and from the API Explorer. This feature is enabled for all applications that use your Square developer account.

  1. Choose View Logs in the Response pane of the API Explorer.

  2. On the API Logs page, choose the API filter at the top of the list. Clear the Select All checkbox, and then choose Payments. The log list is filtered to show only payments requests.

  3. Choose the payment transaction you created in the previous step to view a summary of the transaction log. If a transaction is older than 28 days, it won't appear in the API logs.

  4. Choose Request to view the transaction's HTTP request.

  5. Choose Response to view the transaction's response.

get-started-v2-4.ViewTransaction

Step 5: Verify the transaction in the Seller Dashboard Permalink Get a link to this section

Square reports the preceding transaction in the Seller Dashboard. Because you submitted the API request in the Sandbox, you do not see this transaction in the production Seller Dashboard. Instead, Square reports the transaction in the Sandbox Seller Dashboard associated with the default Sandbox test account you used to take the payment.

  1. Open the Developer Dashboard.

  2. Choose Open next to Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.

  3. Choose Transactions.

  4. On the Transactions page, verify the preceding payment. Make sure you have the appropriate date range selected.

get-started-5.VerifyInSellerDash

What's next? Permalink Get a link to this section

Now that you have signed up for a Square account, created an application, and tested some API requests, you can start building. The Square developer platform provides a collection of APIs and a variety of development tools:

  • Square API. Provides APIs for developers to build on the platform that sellers trust. This includes online payments, creating orders for itemized transactions, product catalog management, customer management, and employee time keeping.

  • Square Backend SDKs. Simplify development by encapsulating the Square API suites.

  • Payments SDKs. Square payments can be processed across multiple channels, including online, in-app, and in-person. The Square developer platform includes server-side APIs that support online payments and mobile SDKs that support mobile payments on seller or buyer mobile devices.

    Square also supports Flutter and React Native for In-App and In-Person payments.

  • Webhooks. Supports push notifications for various Square APIs.

The tools and environments include:

  • Square Sandbox. An isolated Sandbox testing environment.

  • API Explorer. An interactive tool you can use to build, view, and send HTTP requests that call Square APIs.

  • API Logs (beta). 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.

  • The Postman collection. Use the Connect Postman collection to test Square APIs.