Skip to content
This repository was archived by the owner on Apr 23, 2021. It is now read-only.

Latest commit

 

History

History
817 lines (760 loc) · 51.6 KB

README.md

File metadata and controls

817 lines (760 loc) · 51.6 KB

Square logo

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.

Build Status NuGet version Apache-2 license

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

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:

  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.