Square Connect .NET SDK Technical Reference

December 17, 2019 · View on GitHub

Square Connect .NET SDK Technical Reference

The Square Connect .NET SDK is retired (EOL) as of 2019-12-17 and will no longer receive bug fixes or product updates.

If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new slack community for Square Developers

This repository contains the released C# client SDK. Check out our API specification repository for the specification and template files we used to generate this.

Frameworks supported

.NET Standard 2.0

Usage

Option 1: Obtain from NuGet package manager (Recommended)

PM> Install-Package Square.Connect

Option 2: Generating DLLs from source

Dependencies

[RestSharp] (https://www.nuget.org/packages/RestSharp) - 106.3.1 or later
[Json.NET] (https://www.nuget.org/packages/Newtonsoft.Json/) - 11.0.2 or later

Option 1: Run the following command to generate the DLL

[Mac/Linux] /bin/sh build.sh
[Windows] build.bat

Option 2: Import the Square.Connect/Square.Connect.csproj to your solution and build from VS

Then include the DLLs (under the bin folder) in the C# project,

Square.Connect.dll

Getting Started

Use the namespaces:

using Square.Connect.Api;
using Square.Connect.Client;
using Square.Connect.Model;

Example:

using System;
using System.Diagnostics;
using Square.Connect.Api;
using Square.Connect.Client;
using Square.Connect.Model;

namespace Example
{
    public class Example
    {
        readonly Configuration configuration;
        public Example()
        {
            this.configuration = new Configuration(new ApiClient("https://connect.squareup.com"));
            this.configuration.AccessToken = "YOUR_ACCESS_TOKEN";
        }

        // Retrieving your location IDs
        public void RetrieveLocations()
        {
            LocationsApi _locationsApi = new LocationsApi(this.configuration);
            var response = _locationsApi.ListLocations();
        }

        // Charge the card nonce
        public void ChargeNonce()
        {
            // Every payment you process for a given business have a unique idempotency key.
            // If you're unsure whether a particular payment succeeded, you can reattempt
            // it with the same idempotency key without worrying about double charging
            // the buyer.
            string idempotencyKey = Guid.NewGuid().ToString();

            // Monetary amounts are specified in the smallest unit of the applicable currency.
            // This amount is in cents. It's also hard-coded for \$1, which is not very useful.
            int amount = 100;
            string currency = "USD";
            Money money = new Money(amount, currency);

            string nonce = "YOUR_NONCE";
            string locationId = "YOUR_LOCATION_ID";
            CreatePaymentRequest body = new CreatePaymentRequest(SourceId: nonce, IdempotencyKey: idempotencyKey, AmountMoney: money, LocationId: locationId);
            PaymentsApi paymentsApi = new PaymentsApi(this.configuration);
            var response = paymentsApi.CreatePayment(body);
        }
    }
}

More examples are available at connect-api-examples

How to configure sandbox environment

using System;
using System.Diagnostics;
using Square.Connect.Api;
using Square.Connect.Client;
using Square.Connect.Model;

namespace Example
{
    public class Example
    {
        readonly Configuration configuration;
        public Example()
        {
            this.configuration = new Configuration(new ApiClient("https://connect.squareupsandbox.com"));
            this.configuration.AccessToken = "YOUR_SANDBOX_ACCESS_TOKEN";
            LocationsApi locationsApi = new LocationsApi(this.configuration);
        }
    }
}

Documentation for API Endpoints

All URIs are relative to Square Connect Documentation

Class	Method	HTTP request
ApplePayApi	RegisterDomain	POST /v2/apple-pay/domains
CatalogApi	BatchDeleteCatalogObjects	POST /v2/catalog/batch-delete
CatalogApi	BatchRetrieveCatalogObjects	POST /v2/catalog/batch-retrieve
CatalogApi	BatchUpsertCatalogObjects	POST /v2/catalog/batch-upsert
CatalogApi	CatalogInfo	GET /v2/catalog/info
CatalogApi	DeleteCatalogObject	DELETE /v2/catalog/object/{object_id}
CatalogApi	ListCatalog	GET /v2/catalog/list
CatalogApi	RetrieveCatalogObject	GET /v2/catalog/object/{object_id}
CatalogApi	SearchCatalogObjects	POST /v2/catalog/search
CatalogApi	UpdateItemModifierLists	POST /v2/catalog/update-item-modifier-lists
CatalogApi	UpdateItemTaxes	POST /v2/catalog/update-item-taxes
CatalogApi	UpsertCatalogObject	POST /v2/catalog/object
CheckoutApi	CreateCheckout	POST /v2/locations/{location_id}/checkouts
CustomersApi	CreateCustomer	POST /v2/customers
CustomersApi	CreateCustomerCard	POST /v2/customers/{customer_id}/cards
CustomersApi	DeleteCustomer	DELETE /v2/customers/{customer_id}
CustomersApi	DeleteCustomerCard	DELETE /v2/customers/{customer_id}/cards/{card_id}
CustomersApi	ListCustomers	GET /v2/customers
CustomersApi	RetrieveCustomer	GET /v2/customers/{customer_id}
CustomersApi	SearchCustomers	POST /v2/customers/search
CustomersApi	UpdateCustomer	PUT /v2/customers/{customer_id}
EmployeesApi	ListEmployees	GET /v2/employees
EmployeesApi	RetrieveEmployee	GET /v2/employees/{id}
InventoryApi	BatchChangeInventory	POST /v2/inventory/batch-change
InventoryApi	BatchRetrieveInventoryChanges	POST /v2/inventory/batch-retrieve-changes
InventoryApi	BatchRetrieveInventoryCounts	POST /v2/inventory/batch-retrieve-counts
InventoryApi	RetrieveInventoryAdjustment	GET /v2/inventory/adjustment/{adjustment_id}
InventoryApi	RetrieveInventoryChanges	GET /v2/inventory/{catalog_object_id}/changes
InventoryApi	RetrieveInventoryCount	GET /v2/inventory/{catalog_object_id}
InventoryApi	RetrieveInventoryPhysicalCount	GET /v2/inventory/physical-count/{physical_count_id}
LaborApi	CreateBreakType	POST /v2/labor/break-types
LaborApi	CreateShift	POST /v2/labor/shifts
LaborApi	DeleteBreakType	DELETE /v2/labor/break-types/{id}
LaborApi	DeleteShift	DELETE /v2/labor/shifts/{id}
LaborApi	GetBreakType	GET /v2/labor/break-types/{id}
LaborApi	GetEmployeeWage	GET /v2/labor/employee-wages/{id}
LaborApi	GetShift	GET /v2/labor/shifts/{id}
LaborApi	ListBreakTypes	GET /v2/labor/break-types
LaborApi	ListEmployeeWages	GET /v2/labor/employee-wages
LaborApi	ListWorkweekConfigs	GET /v2/labor/workweek-configs
LaborApi	SearchShifts	POST /v2/labor/shifts/search
LaborApi	UpdateBreakType	PUT /v2/labor/break-types/{id}
LaborApi	UpdateShift	PUT /v2/labor/shifts/{id}
LaborApi	UpdateWorkweekConfig	PUT /v2/labor/workweek-configs/{id}
LocationsApi	CreateLocation	POST /v2/locations
LocationsApi	ListLocations	GET /v2/locations
LocationsApi	RetrieveLocation	GET /v2/locations/{location_id}
LocationsApi	UpdateLocation	PUT /v2/locations/{location_id}
MerchantsApi	ListMerchants	GET /v2/merchants
MerchantsApi	RetrieveMerchant	GET /v2/merchants/{merchant_id}
MobileAuthorizationApi	CreateMobileAuthorizationCode	POST /mobile/authorization-code
OAuthApi	ObtainToken	POST /oauth2/token
OAuthApi	RenewToken	POST /oauth2/clients/{client_id}/access-token/renew
OAuthApi	RevokeToken	POST /oauth2/revoke
OrdersApi	BatchRetrieveOrders	POST /v2/locations/{location_id}/orders/batch-retrieve
OrdersApi	CreateOrder	POST /v2/locations/{location_id}/orders
OrdersApi	PayOrder	POST /v2/orders/{order_id}/pay
OrdersApi	SearchOrders	POST /v2/orders/search
OrdersApi	UpdateOrder	PUT /v2/locations/{location_id}/orders/{order_id}
PaymentsApi	CancelPayment	POST /v2/payments/{payment_id}/cancel
PaymentsApi	CancelPaymentByIdempotencyKey	POST /v2/payments/cancel
PaymentsApi	CompletePayment	POST /v2/payments/{payment_id}/complete
PaymentsApi	CreatePayment	POST /v2/payments
PaymentsApi	GetPayment	GET /v2/payments/{payment_id}
PaymentsApi	ListPayments	GET /v2/payments
RefundsApi	GetPaymentRefund	GET /v2/refunds/{refund_id}
RefundsApi	ListPaymentRefunds	GET /v2/refunds
RefundsApi	RefundPayment	POST /v2/refunds
ReportingApi	ListAdditionalRecipientReceivableRefunds	GET /v2/locations/{location_id}/additional-recipient-receivable-refunds
ReportingApi	ListAdditionalRecipientReceivables	GET /v2/locations/{location_id}/additional-recipient-receivables
TransactionsApi	CaptureTransaction	POST /v2/locations/{location_id}/transactions/{transaction_id}/capture
TransactionsApi	Charge	POST /v2/locations/{location_id}/transactions
TransactionsApi	CreateRefund	POST /v2/locations/{location_id}/transactions/{transaction_id}/refund
TransactionsApi	ListRefunds	GET /v2/locations/{location_id}/refunds
TransactionsApi	ListTransactions	GET /v2/locations/{location_id}/transactions
TransactionsApi	RetrieveTransaction	GET /v2/locations/{location_id}/transactions/{transaction_id}
TransactionsApi	VoidTransaction	POST /v2/locations/{location_id}/transactions/{transaction_id}/void
V1EmployeesApi	CreateEmployee	POST /v1/me/employees
V1EmployeesApi	CreateEmployeeRole	POST /v1/me/roles
V1EmployeesApi	CreateTimecard	POST /v1/me/timecards
V1EmployeesApi	DeleteTimecard	DELETE /v1/me/timecards/{timecard_id}
V1EmployeesApi	ListCashDrawerShifts	GET /v1/{location_id}/cash-drawer-shifts
V1EmployeesApi	ListEmployeeRoles	GET /v1/me/roles
V1EmployeesApi	ListEmployees	GET /v1/me/employees
V1EmployeesApi	ListTimecardEvents	GET /v1/me/timecards/{timecard_id}/events
V1EmployeesApi	ListTimecards	GET /v1/me/timecards
V1EmployeesApi	RetrieveCashDrawerShift	GET /v1/{location_id}/cash-drawer-shifts/{shift_id}
V1EmployeesApi	RetrieveEmployee	GET /v1/me/employees/{employee_id}
V1EmployeesApi	RetrieveEmployeeRole	GET /v1/me/roles/{role_id}
V1EmployeesApi	RetrieveTimecard	GET /v1/me/timecards/{timecard_id}
V1EmployeesApi	UpdateEmployee	PUT /v1/me/employees/{employee_id}
V1EmployeesApi	UpdateEmployeeRole	PUT /v1/me/roles/{role_id}
V1EmployeesApi	UpdateTimecard	PUT /v1/me/timecards/{timecard_id}
V1ItemsApi	AdjustInventory	POST /v1/{location_id}/inventory/{variation_id}
V1ItemsApi	ApplyFee	PUT /v1/{location_id}/items/{item_id}/fees/{fee_id}
V1ItemsApi	ApplyModifierList	PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	CreateCategory	POST /v1/{location_id}/categories
V1ItemsApi	CreateDiscount	POST /v1/{location_id}/discounts
V1ItemsApi	CreateFee	POST /v1/{location_id}/fees
V1ItemsApi	CreateItem	POST /v1/{location_id}/items
V1ItemsApi	CreateModifierList	POST /v1/{location_id}/modifier-lists
V1ItemsApi	CreateModifierOption	POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options
V1ItemsApi	CreatePage	POST /v1/{location_id}/pages
V1ItemsApi	CreateVariation	POST /v1/{location_id}/items/{item_id}/variations
V1ItemsApi	DeleteCategory	DELETE /v1/{location_id}/categories/{category_id}
V1ItemsApi	DeleteDiscount	DELETE /v1/{location_id}/discounts/{discount_id}
V1ItemsApi	DeleteFee	DELETE /v1/{location_id}/fees/{fee_id}
V1ItemsApi	DeleteItem	DELETE /v1/{location_id}/items/{item_id}
V1ItemsApi	DeleteModifierList	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	DeleteModifierOption	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}
V1ItemsApi	DeletePage	DELETE /v1/{location_id}/pages/{page_id}
V1ItemsApi	DeletePageCell	DELETE /v1/{location_id}/pages/{page_id}/cells
V1ItemsApi	DeleteVariation	DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id}
V1ItemsApi	ListCategories	GET /v1/{location_id}/categories
V1ItemsApi	ListDiscounts	GET /v1/{location_id}/discounts
V1ItemsApi	ListFees	GET /v1/{location_id}/fees
V1ItemsApi	ListInventory	GET /v1/{location_id}/inventory
V1ItemsApi	ListItems	GET /v1/{location_id}/items
V1ItemsApi	ListModifierLists	GET /v1/{location_id}/modifier-lists
V1ItemsApi	ListPages	GET /v1/{location_id}/pages
V1ItemsApi	RemoveFee	DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id}
V1ItemsApi	RemoveModifierList	DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	RetrieveItem	GET /v1/{location_id}/items/{item_id}
V1ItemsApi	RetrieveModifierList	GET /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	UpdateCategory	PUT /v1/{location_id}/categories/{category_id}
V1ItemsApi	UpdateDiscount	PUT /v1/{location_id}/discounts/{discount_id}
V1ItemsApi	UpdateFee	PUT /v1/{location_id}/fees/{fee_id}
V1ItemsApi	UpdateItem	PUT /v1/{location_id}/items/{item_id}
V1ItemsApi	UpdateModifierList	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	UpdateModifierOption	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}
V1ItemsApi	UpdatePage	PUT /v1/{location_id}/pages/{page_id}
V1ItemsApi	UpdatePageCell	PUT /v1/{location_id}/pages/{page_id}/cells
V1ItemsApi	UpdateVariation	PUT /v1/{location_id}/items/{item_id}/variations/{variation_id}
V1LocationsApi	ListLocations	GET /v1/me/locations
V1LocationsApi	RetrieveBusiness	GET /v1/me
V1TransactionsApi	CreateRefund	POST /v1/{location_id}/refunds
V1TransactionsApi	ListBankAccounts	GET /v1/{location_id}/bank-accounts
V1TransactionsApi	ListOrders	GET /v1/{location_id}/orders
V1TransactionsApi	ListPayments	GET /v1/{location_id}/payments
V1TransactionsApi	ListRefunds	GET /v1/{location_id}/refunds
V1TransactionsApi	ListSettlements	GET /v1/{location_id}/settlements
V1TransactionsApi	RetrieveBankAccount	GET /v1/{location_id}/bank-accounts/{bank_account_id}
V1TransactionsApi	RetrieveOrder	GET /v1/{location_id}/orders/{order_id}
V1TransactionsApi	RetrievePayment	GET /v1/{location_id}/payments/{payment_id}
V1TransactionsApi	RetrieveSettlement	GET /v1/{location_id}/settlements/{settlement_id}
V1TransactionsApi	UpdateOrder	PUT /v1/{location_id}/orders/{order_id}

Documentation for Models

Documentation for Authorization

oauth2

Type: OAuth
Flow: accessCode
Authorization URL: https://connect.squareup.com/oauth2/authorize
Scopes:
- BANK_ACCOUNTS_READ: HTTP Method: `GET` Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.
- CUSTOMERS_READ: HTTP Method: `GET` Grants read access to customer information. For example, to call the ListCustomers endpoint.
- CUSTOMERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to customer information. For example, to create and update customer profiles.
- EMPLOYEES_READ: HTTP Method: `GET` Grants read access to employee profile information. For example, to call the Connect v1 Employees API.
- EMPLOYEES_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee profile information. For example, to create and modify employee profiles.
- INVENTORY_READ: HTTP Method: `GET` Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.
- INVENTORY_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.
- ITEMS_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
- ITEMS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to product catalog information. For example, to modify or add to a product catalog.
- MERCHANT_PROFILE_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
- ORDERS_READ: HTTP Method: `GET` Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.
- ORDERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to order information. For example, to call the CreateCheckout endpoint.
- PAYMENTS_READ: HTTP Method: `GET` Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.
- PAYMENTS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process payments with the Payments or Checkout API.
- PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: HTTP Method: `POST`, `PUT`, `DELETE` Allow third party applications to deduct a portion of each transaction amount. Required to use multiparty transaction functionality with the Payments API.
- PAYMENTS_WRITE_IN_PERSON: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to payments and refunds information. For example, to process in-person payments.
- SETTLEMENTS_READ: HTTP Method: `GET` Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.
- TIMECARDS_READ: HTTP Method: `GET` Grants read access to employee timecard information. For example, to call the Connect v2 SearchShifts endpoint.
- TIMECARDS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee shift information. For example, to create and modify employee shifts.
- TIMECARDS_SETTINGS_READ: HTTP Method: `GET` Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.
- TIMECARDS_SETTINGS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.

oauth2ClientSecret

Type: API key
API key parameter name: Authorization
Location: HTTP header

Pagination of V1 Endpoints

V1 Endpoints return pagination information via HTTP headers. In order to obtain response headers and extract the batch_token parameter you will need to follow the following steps:

Use the full information endpoint methods of each API to get the ApiResponse object. They are named as their simple counterpart with a WithHttpInfo suffix. Hence ListEmployeeRoles would be called ListEmployeeRolesWithHttpInfo. This method returns an ApiResponse<List<V1EmployeeRole>> object.
Use string batchToken = response.BatchToken to get the token and proceed to get the following page if a token is present.

Example

using System;
using System.Diagnostics;
using Square.Connect.Api;
using Square.Connect.Client;
using Square.Connect.Model;

namespace Example
{
    public class ListEmployeeRolesExample
    {
        public void main()
        {
            // Configure OAuth2 access token for authorization: oauth2
            Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new V1EmployeesApi();
            var order = order_example;  // string | The order in which employees are listed in the response, based on their created_at field.Default value: ASC  (optional)
            var limit = 56;  // int? | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. (optional)
            string batchToken = null;

            try
            {
                do {
                    // Provides summary information for all of a business's employee roles.
                    ApiResponse<List<V1EmployeeRole>> response = apiInstance.ListEmployeeRolesWithHttpInfo(order, limit, batchToken);
                    batchToken = response.BatchToken
                    Debug.WriteLine(response.Data);
                } while (batchToken != null);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling V1EmployeesApi.ListEmployeeRolesWithHttpInfo: " + e.Message );
            }
        }
    }
}

Contributing

Send bug reports, feature requests, and code contributions to the API specifications repository, as this repository contains only the generated SDK code.

License

Copyright 2017 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.