If you're new to developing Square integrations using the Square .NET SDK, you should try the Quickstart. It provides step-by-step instructions to explore your first project.
This topic explains how to configure a client, how to securely provide credentials (access tokens) to authenticate your request, the API call patterns, how to pass parameters, and how to process responses.
using directive allows you to use types defined in a namespace without specifying the fully qualified namespace of that type. You add the following
using directive to import all the types from the Square namespace:
To use the Square API, instantiate a
SquareClient object and initialize it with the appropriate environment and corresponding access token. For an introduction to these environments, see Create an Account and Application.
For testing, Square provides a Sandbox environment.
The next section (Configure credentials securely) explains how you might avoid hardcoding credentials (access tokens) in your application.
To access production resources, set the environment to
To set a custom environment, provide a
CustomUrland set the environment to
Each Square API request must be authenticated. Don't hardcode credentials (access tokens) in your code. The Quickstart exercise uses a configuration file in the project to store credentials. The code then uses the .NET API calls to read the credentials as shown in the following C# code fragment:
In the code, appsettings.json is the configuration file, as shown in the following example:
The Square .NET SDK uses the Task-based Asynchronous Pattern (TAP) for its asynchronous implementation. The Square .NET SDK asynchronous methods are based on the Task class or the Task<TResult> class. For more information about TAP, see Task-based Asynchronous Pattern (TAP).
You can call Square async API methods from within functions declared with the async keyword, as shown:
You can set the main function as async to ensure that all Square API calls that your application makes are asynchronous.
Square.Models namespace, every object is a model. For example, complex types
Order are all models defined in the namespace. You pass these models, with values, as parameters as shown in the following example. The example passes the
Address model as a parameter to create a new customer.
The Square API endpoints can have path parameters, query parameters, and a request body. When you make corresponding method calls using the Square .NET SDK, you provide the values as follows:
Request body - For example,
Customerobject in the body. In the Square .NET SDK, you use the builder pattern to specify the request body.
Path and query parameters - For example:
RetrieveCustomerendpoint has a
customer_idpath parameter (
ListCustomersendpoint has several query parameters such as
You provide these as parameters to the method calls. The following example passes the
customer_idpath parameter as a parameter to the
For an example of query parameters, see Pagination.
You can configure the number of retries and the timeout values for HTTP requests when using the Square .NET SDK:
Retries - By default, the Square SDK doesn't retry a failed request. When your application starts, the Square SDK sets the number of retries to 0. You have the option to configure a different value when you create a client. Retries can help improve application stability by allowing applications to handle momentary failures in connecting to a service by transparently retrying a failed request.
Timeout - Timeout is the time period that a client waits for a server response. The Square SDK sets the default timeout to 60 seconds. On timeout, the SDK throws an exception. You have the option to configure a timeout value at the client level. The maximum timeout can be the InfiniteTimeSpan constant.
The following C# code fragment specifies the
HttpClientConfig parameter in creating a client. The configuration sets the number of retries to 2 and the timeout to 60 seconds.
Configuring a client with long timeout values and a high number of retries can cause some SDK operations to appear unresponsive. There are several considerations that apply when configuring the timeout and retries. These include:
- For network issues (decrease in network connectivity and response speed), how should the application respond? Do you want the call to fail fast, or do you want the application to retry the failed call?
- Buyer-facing applications might need to be responsive compared to a background job that can tolerate increased latency due increased timeout values and retries.
The response object contains the
HttpContext that describes both the request and the response.
- If an API call succeeds, a response object containing
HttpContextis returned. This
HttpContextdescribes both the request and the response.
- If an API call fails, you get an
ApiException(see ApiException Class).
For more information, see Square API errors.