C# client library for the Square Connect APIs
Clone or download
Latest commit 96c75c7 Dec 12, 2018

README.md

Square Connect C# SDK Build StatusNuGet version

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

Obtain from NuGet package manager (Recommended)

PM> Install-Package Square.Connect

Generating DLLs from source

Dependencies

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
    {
        public Example()
        {
            Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";
        }

        // Retrieving your location IDs
        public void RetrieveLocations()
        {
            LocationsApi _locationsApi = new LocationsApi();
            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, Money.ToCurrencyEnum(currency));

            string nonce = "YOUR_NONCE";
            string locationId = "YOUR_LOCATION_ID";
            ChargeRequest body = new ChargeRequest(AmountMoney: money, IdempotencyKey: idempotencyKey, CardNonce: nonce);
            TransactionsApi transactionsApi = new TransactionsApi();
            var response = transactionsApi.Charge(locationId, body);
        }
    }
}

More examples are available at connect-api-examples

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}
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}
LocationsApi ListLocations GET /v2/locations
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
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:
    • MERCHANT_PROFILE_READ: GET endpoints related to a merchant's business and location entities. Almost all Connect API applications need this permission in order to obtain a merchant's location IDs
    • PAYMENTS_READ: GET endpoints related to transactions and refunds
    • PAYMENTS_WRITE: POST, PUT, and DELETE endpoints related to transactions and refunds. E-commerce applications must request this permission
    • CUSTOMERS_READ: GET endpoints related to customer management
    • CUSTOMERS_WRITE: POST, PUT, and DELETE endpoints related to customer management
    • SETTLEMENTS_READ: GET endpoints related to settlements (deposits)
    • BANK_ACCOUNTS_READ: GET endpoints related to a merchant's bank accounts
    • ITEMS_READ: GET endpoints related to a merchant's item library
    • ITEMS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's item library
    • ORDERS_READ: GET endpoints related to a merchant's orders
    • ORDERS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's orders
    • EMPLOYEES_READ: GET endpoints related to employee management
    • EMPLOYEES_WRITE: POST, PUT, and DELETE endpoints related to employee management
    • TIMECARDS_READ: GET endpoints related to employee timecards
    • TIMECARDS_WRITE: POST, PUT, and DELETE endpoints related to employee timecards
    • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: Allow third party applications to deduct a portion of each transaction amount.
    • PAYMENTS_WRITE_IN_PERSON: POST, PUT, and DELETE endpoints. Grants write access to transaction and refunds information.
    • INVENTORY_READ: GET endpoints related to a merchant's inventory
    • INVENTORY_WRITE: POST, PUT, and DELETE endpoints related to a merchant's inventory

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:

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

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