Square .NET SDK Quickstart

Learn how to quickly set up and test the Square .NET SDK.

Link to section

Prepare for the Quickstart

Before you begin, you need a Square account and account credentials. You use the Square Sandbox for the Quickstart exercise.

  1. Create a Square account and an application. For more information, see Create an Account and Application.
  2. Get a Sandbox access token from the Developer Console. For more information, see Make your First API Call.

You can now follow one of the following workflows depending on whether you're using Visual Studio.

Note

If you prefer to skip the following setup steps, download the Square .NET SDK Quickstart sample and follow the instructions in the README.

Link to section

Option 1: Cross platform

Use the following steps to create a project if you're using a non-Windows computer and don't use Visual Studio. These steps use the .NET command-line interface. Make sure you have .NET installed on your computer. For example, if you're using a Mac, see Install .NET on macOS.

Link to section

Create a project

  1. Open a new terminal window. Find or create an operating system folder under which you can create a .NET project.

  2. In that folder, run the following command to create the .NET project:

    dotnet new console --name ExploreLocationsAPI
  3. Don't add your credentials to the source file. You add an application settings file to the project to store credentials.

    1. Go to the newly created ExploreLocationsAPI folder and add the following appsettings.json file:

      { "AppSettings": { "AccessToken": "YOUR-SANDBOX-ACCESS-TOKEN" } }

      See the following example:

      { "AppSettings": { "AccessToken": "EAAAEFeOs3UYyCct-9FcmbUwUp7Hm1cuaqTRwOOnkw1F0TGKjtKO0avgjexample" } }
    2. Update the JSON file by providing your Sandbox access token.

  4. Run the following commands to install the NuGet packages from the NuGet package manager:

    dotnet add package Square dotnet add package Microsoft.Extensions.Configuration.Json dotnet add package Microsoft.Extensions.Configuration

    The Microsoft.Extensions.Configuration and package Microsoft.Extensions.Configuration.Json packages are used to manage the application settings file (such as read credentials).

Link to section

Write code

  1. In the ExploreLocationsAPI folder, find and open Program.cs in your code editor.

  2. Replace the contents with the following code and save the file:

    This code does the following:

    • Reads your Square access token from the appsettings.json file.
    • Creates a SquareClient using the access token.
    • Calls the ListLocationsAsync method to retrieve the locations.

    If the request is successful, the code prints the location information on the terminal.

  3. Update the code to provide the full path of the appsettings.json file.

    var builder = new ConfigurationBuilder() .AddJsonFile($"<file-path>/appsettings.json", true, true);
Link to section

Run the application

  1. Run the following command:

    dotnet run

    You should see at least one location (Square creates one location when you create a Square account).

Link to section

Option 2: Windows platform

You perform this Quickstart exercise on a Windows computer using Visual Studio and .NET Core. Make sure you have the following:

Link to section

Create a project

  1. Open Visual Studio and create a new project using the C# Console Application template. Name the project ExploreLocationsAPI.

  2. After the project loads, right-click the project, choose Add, and then choose NuGet Packages.

  3. Search the following NuGet packages and install them in the project:

    Square Microsoft.Extensions.Configuration.Json Microsoft.Extensions.Configuration
  4. Add an appsettings.json file to the project.

    1. Right-click the project, choose Add, choose New File, and then choose Empty text file. Specify the file name as appsettings.json.

    2. Add the following JSON:

      { "AppSettings": { "AccessToken": "{YOUR-SANDBOX-ACCESS-TOKEN}" } }
    3. Update the preceding JSON by providing your Sandbox access token.

    4. Update the file properties. Right-click appsettings.json, and then choose Properties. In the Copy to Output Directory drop-down list, choose Copy if newer.

Link to section

Write code

  1. In the ExploreCustomersAPI project, find and open Program.cs.

  2. Replace the contents with the following code:

  3. Save the file.

    This code does the following:

    • Reads your Square access token from the appsettings.json file.
    • Creates a SquareClient using the access token.
    • Calls the ListLocationsAsync method to retrieve the locations.
    • If the request is successful, the code prints the location information on the terminal.
Link to section

Run the application

  1. Build and run the application.
  2. Verify the result. You should see at least one location (Square creates one location when you create a Square account).
Link to section

What's next

You can explore one of the following paths:

  • Explore the .NET SDK and try examples on your own. For more information, see SDK reference library on GitHub.
  • Learn more introductory information about using the .NET SDK.
Link to section

See also