Square .NET SDK Quickstart

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

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 Get a personal access token.

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

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.

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

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:

   using System;
   using Square;
   using Square.Models;
   using Square.Exceptions;
   using Square.Authentication;
   using Microsoft.Extensions.Configuration;
   
   namespace ExploreLocationsAPI
   {
       public class Program
       {
           private static ISquareClient client;
           private static IConfigurationRoot config;
   
           static void Main(string[] args)
           {
   var builder = new ConfigurationBuilder()
    .AddJsonFile($"appsettings.json", true, true);
   
   config = builder.Build();
   var accessToken = config["AppSettings:AccessToken"];
   
   client = new SquareClient.Builder()
       .BearerAuthCredentials(
            new BearerAuthModel.Builder(
                accessToken
            )
            .Build())
       .Environment(Square.Environment.Sandbox)
       .Build();
   
   RetrieveLocationsAsync().Wait();
           }
   
           static async Task RetrieveLocationsAsync()
           {
   try
   {
       ListLocationsResponse response = await client.LocationsApi.ListLocationsAsync();
       foreach (Location location in response.Locations)
       {
           Console.WriteLine("location:\n  country =  {0} name = {1}",
   location.Country, location.Name);
       }
   }
   catch (ApiException e)
   {
       var errors = e.Errors;
       var statusCode = e.ResponseCode;
       var httpContext = e.HttpContext;
       Console.WriteLine("ApiException occurred:");
       Console.WriteLine("Headers:");
       foreach (var item in httpContext.Request.Headers)
       {
           //Display all the headers except Authorization
           if (item.Key != "Authorization")
           {
   Console.WriteLine("\t{0}: \t{1}", item.Key, item.Value);
           }
       }
       Console.WriteLine("Status Code: \t{0}", statusCode);
       foreach (Error error in errors)
       {
           Console.WriteLine("Error Category:{0} Code:{1} Detail:{2}", error.Category, error.Code, error.Detail);
       }
   
       // Your error handling code
   }
   catch (Exception e)
   {
       Console.WriteLine("Exception occurred");
       // Your error handling code
   }
           }
       }
   }

   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);

1. Run the following command:

   dotnet run

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

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

• Microsoft Visual Studio.
• Microsoft .NET Standard 2.0 or later. This is typically included by default when installing a recent version of Visual Studio. For more information, see Install .NET on Windows.

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.

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

2. Replace the contents with the following code:

   using System;
   using Square;
   using Square.Models;
   using Square.Exceptions;
   using Square.Authentication;
   using Microsoft.Extensions.Configuration;
   
   namespace ExploreLocationsAPI
   {
       public class Program
       {
           private static ISquareClient client;
           private static IConfigurationRoot config;
   
           static void Main(string[] args)
           {
   var builder = new ConfigurationBuilder()
    .AddJsonFile($"appsettings.json", true, true);
   
   config = builder.Build();
   var accessToken = config["AppSettings:AccessToken"];
   
   client = new SquareClient.Builder()
       .BearerAuthCredentials(
            new BearerAuthModel.Builder(
                accessToken
            )
            .Build())
       .Environment(Square.Environment.Sandbox)
       .Build();
   
   RetrieveLocationsAsync().Wait();
           }
   
           static async Task RetrieveLocationsAsync()
           {
   try
   {
       ListLocationsResponse response = await client.LocationsApi.ListLocationsAsync();
       foreach (Location location in response.Locations)
       {
           Console.WriteLine("location:\n  country =  {0} name = {1}",
   location.Country, location.Name);
       }
   }
   catch (ApiException e)
   {
       var errors = e.Errors;
       var statusCode = e.ResponseCode;
       var httpContext = e.HttpContext;
       Console.WriteLine("ApiException occurred:");
       Console.WriteLine("Headers:");
       foreach (var item in httpContext.Request.Headers)
       {
           //Display all the headers except Authorization
           if (item.Key != "Authorization")
           {
   Console.WriteLine("\t{0}: \t{1}", item.Key, item.Value);
           }
       }
       Console.WriteLine("Status Code: \t{0}", statusCode);
       foreach (Error error in errors)
       {
           Console.WriteLine("Error Category:{0} Code:{1} Detail:{2}", error.Category, error.Code, error.Detail);
       }
   
       // Your error handling code
   }
   catch (Exception e)
   {
       Console.WriteLine("Exception occurred");
       // Your error handling 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.

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

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.

• Set up your Square SDK for a .NET Project
• Using the Square .NET SDK
• Common Square API Patterns