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

Latest commit

 

History

History
916 lines (844 loc) · 55.8 KB

README.md

File metadata and controls

916 lines (844 loc) · 55.8 KB

Square logo

Square Connect Java SDK Technical Reference

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

Maven Central 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

Requirements

Java 8

Building the API client library requires Maven to be installed.

Installation

Option 1: Maven users

Add this dependency to your project's POM:

<dependency>
    <groupId>com.squareup</groupId>
    <artifactId>connect</artifactId>
    <version>2.20191120.0</version>
    <scope>compile</scope>
</dependency>

Option 2: Gradle users

Add this dependency to your project's build file:

compile "com.squareup:connect:2.20191120.0"

Option 3: Build and Install locally

To install the API client library to your local Maven repository, simply execute:

mvn install -DskipTests

To run tests, you would need to create below accounts.json under travis-ci folder.

{
  "US-Prod": {
    "email": "your_email",
    "access_token": "your_access_token",
    "location_id": "your_location_id",
    "application_id": "your_application_id"
  },
  "US-Prod-Sandbox": {
    "email": "your_email",
    "access_token": "your_sandbox_access_token",
    "location_id": "your_sandbox_location_id",
    "application_id": "your_sandbox_application_id"
  }
}
mvn install

Option 4: Others

At first generate the JAR by executing:

mvn package

Then manually install the following JARs:

  • target/connect-2.20191120.0.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import com.squareup.connect.ApiClient;
import com.squareup.connect.ApiException;
import com.squareup.connect.Configuration;
import com.squareup.connect.api.LocationsApi;
import com.squareup.connect.auth.OAuth;
import com.squareup.connect.models.Location;

import java.io.File;
import java.util.*;

public class Example {

    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();

        // Configure OAuth2 access token for authorization: oauth2
        OAuth oauth2 = (OAuth) apiClient.getAuthentication("oauth2");
        oauth2.setAccessToken("YOUR_ACCESS_TOKEN");

        // List all locations
        LocationsApi locationsApi = new LocationsApi();
        locationsApi.setApiClient(apiClient);

        try {
            List<Location> locations = locationsApi.listLocations().getLocations();
            System.out.println(locations);
        } catch (ApiException e) {
            System.err.println("Exception when calling API");
            e.printStackTrace();
        }
    }
}

How to configure sandbox environment

import com.squareup.connect.ApiClient;
import com.squareup.connect.ApiException;
import com.squareup.connect.Configuration;
import com.squareup.connect.api.LocationsApi;
import com.squareup.connect.auth.OAuth;
import com.squareup.connect.models.Location;

import java.io.File;
import java.util.*;

public class Example {

    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        // Set sandbox url
        apiClient.setBasePath('https://connect.squareupsandbox.com');

        // Configure OAuth2 access token for authorization: oauth2
        OAuth oauth2 = (OAuth) apiClient.getAuthentication("oauth2");
        // Set your sandbox token
        oauth2.setAccessToken("YOUR_SANDBOX_ACCESS_TOKEN");

        LocationsApi locationsApi = new LocationsApi();
    }
}

Documentation for API Endpoints

All URIs are relative to https://connect.squareup.com

Class Method HTTP request Description
ApplePayApi registerDomain POST /v2/apple-pay/domains RegisterDomain
CatalogApi batchDeleteCatalogObjects POST /v2/catalog/batch-delete BatchDeleteCatalogObjects
CatalogApi batchRetrieveCatalogObjects POST /v2/catalog/batch-retrieve BatchRetrieveCatalogObjects
CatalogApi batchUpsertCatalogObjects POST /v2/catalog/batch-upsert BatchUpsertCatalogObjects
CatalogApi catalogInfo GET /v2/catalog/info CatalogInfo
CatalogApi deleteCatalogObject DELETE /v2/catalog/object/{object_id} DeleteCatalogObject
CatalogApi listCatalog GET /v2/catalog/list ListCatalog
CatalogApi retrieveCatalogObject GET /v2/catalog/object/{object_id} RetrieveCatalogObject
CatalogApi searchCatalogObjects POST /v2/catalog/search SearchCatalogObjects
CatalogApi updateItemModifierLists POST /v2/catalog/update-item-modifier-lists UpdateItemModifierLists
CatalogApi updateItemTaxes POST /v2/catalog/update-item-taxes UpdateItemTaxes
CatalogApi upsertCatalogObject POST /v2/catalog/object UpsertCatalogObject
CheckoutApi createCheckout POST /v2/locations/{location_id}/checkouts CreateCheckout
CustomersApi createCustomer POST /v2/customers CreateCustomer
CustomersApi createCustomerCard POST /v2/customers/{customer_id}/cards CreateCustomerCard
CustomersApi deleteCustomer DELETE /v2/customers/{customer_id} DeleteCustomer
CustomersApi deleteCustomerCard DELETE /v2/customers/{customer_id}/cards/{card_id} DeleteCustomerCard
CustomersApi listCustomers GET /v2/customers ListCustomers
CustomersApi retrieveCustomer GET /v2/customers/{customer_id} RetrieveCustomer
CustomersApi searchCustomers POST /v2/customers/search SearchCustomers
CustomersApi updateCustomer PUT /v2/customers/{customer_id} UpdateCustomer
EmployeesApi listEmployees GET /v2/employees ListEmployees
EmployeesApi retrieveEmployee GET /v2/employees/{id} RetrieveEmployee
InventoryApi batchChangeInventory POST /v2/inventory/batch-change BatchChangeInventory
InventoryApi batchRetrieveInventoryChanges POST /v2/inventory/batch-retrieve-changes BatchRetrieveInventoryChanges
InventoryApi batchRetrieveInventoryCounts POST /v2/inventory/batch-retrieve-counts BatchRetrieveInventoryCounts
InventoryApi retrieveInventoryAdjustment GET /v2/inventory/adjustment/{adjustment_id} RetrieveInventoryAdjustment
InventoryApi retrieveInventoryChanges GET /v2/inventory/{catalog_object_id}/changes RetrieveInventoryChanges
InventoryApi retrieveInventoryCount GET /v2/inventory/{catalog_object_id} RetrieveInventoryCount
InventoryApi retrieveInventoryPhysicalCount GET /v2/inventory/physical-count/{physical_count_id} RetrieveInventoryPhysicalCount
LaborApi createBreakType POST /v2/labor/break-types CreateBreakType
LaborApi createShift POST /v2/labor/shifts CreateShift
LaborApi deleteBreakType DELETE /v2/labor/break-types/{id} DeleteBreakType
LaborApi deleteShift DELETE /v2/labor/shifts/{id} DeleteShift
LaborApi getBreakType GET /v2/labor/break-types/{id} GetBreakType
LaborApi getEmployeeWage GET /v2/labor/employee-wages/{id} GetEmployeeWage
LaborApi getShift GET /v2/labor/shifts/{id} GetShift
LaborApi listBreakTypes GET /v2/labor/break-types ListBreakTypes
LaborApi listEmployeeWages GET /v2/labor/employee-wages ListEmployeeWages
LaborApi listWorkweekConfigs GET /v2/labor/workweek-configs ListWorkweekConfigs
LaborApi searchShifts POST /v2/labor/shifts/search SearchShifts
LaborApi updateBreakType PUT /v2/labor/break-types/{id} UpdateBreakType
LaborApi updateShift PUT /v2/labor/shifts/{id} UpdateShift
LaborApi updateWorkweekConfig PUT /v2/labor/workweek-configs/{id} UpdateWorkweekConfig
LocationsApi createLocation POST /v2/locations CreateLocation
LocationsApi listLocations GET /v2/locations ListLocations
LocationsApi retrieveLocation GET /v2/locations/{location_id} RetrieveLocation
LocationsApi updateLocation PUT /v2/locations/{location_id} UpdateLocation
MerchantsApi listMerchants GET /v2/merchants ListMerchants
MerchantsApi retrieveMerchant GET /v2/merchants/{merchant_id} RetrieveMerchant
MobileAuthorizationApi createMobileAuthorizationCode POST /mobile/authorization-code CreateMobileAuthorizationCode
OAuthApi obtainToken POST /oauth2/token ObtainToken
OAuthApi renewToken POST /oauth2/clients/{client_id}/access-token/renew RenewToken
OAuthApi revokeToken POST /oauth2/revoke RevokeToken
OrdersApi batchRetrieveOrders POST /v2/locations/{location_id}/orders/batch-retrieve BatchRetrieveOrders
OrdersApi createOrder POST /v2/locations/{location_id}/orders CreateOrder
OrdersApi payOrder POST /v2/orders/{order_id}/pay PayOrder
OrdersApi searchOrders POST /v2/orders/search SearchOrders
OrdersApi updateOrder PUT /v2/locations/{location_id}/orders/{order_id} UpdateOrder
PaymentsApi cancelPayment POST /v2/payments/{payment_id}/cancel CancelPayment
PaymentsApi cancelPaymentByIdempotencyKey POST /v2/payments/cancel CancelPaymentByIdempotencyKey
PaymentsApi completePayment POST /v2/payments/{payment_id}/complete CompletePayment
PaymentsApi createPayment POST /v2/payments CreatePayment
PaymentsApi getPayment GET /v2/payments/{payment_id} GetPayment
PaymentsApi listPayments GET /v2/payments ListPayments
RefundsApi getPaymentRefund GET /v2/refunds/{refund_id} GetPaymentRefund
RefundsApi listPaymentRefunds GET /v2/refunds ListPaymentRefunds
RefundsApi refundPayment POST /v2/refunds RefundPayment
ReportingApi listAdditionalRecipientReceivableRefunds GET /v2/locations/{location_id}/additional-recipient-receivable-refunds ListAdditionalRecipientReceivableRefunds
ReportingApi listAdditionalRecipientReceivables GET /v2/locations/{location_id}/additional-recipient-receivables ListAdditionalRecipientReceivables
TransactionsApi captureTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/capture CaptureTransaction
TransactionsApi charge POST /v2/locations/{location_id}/transactions Charge
TransactionsApi createRefund POST /v2/locations/{location_id}/transactions/{transaction_id}/refund CreateRefund
TransactionsApi listRefunds GET /v2/locations/{location_id}/refunds ListRefunds
TransactionsApi listTransactions GET /v2/locations/{location_id}/transactions ListTransactions
TransactionsApi retrieveTransaction GET /v2/locations/{location_id}/transactions/{transaction_id} RetrieveTransaction
TransactionsApi voidTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/void VoidTransaction
V1EmployeesApi createEmployee POST /v1/me/employees CreateEmployee
V1EmployeesApi createEmployeeRole POST /v1/me/roles CreateEmployeeRole
V1EmployeesApi createTimecard POST /v1/me/timecards CreateTimecard
V1EmployeesApi deleteTimecard DELETE /v1/me/timecards/{timecard_id} DeleteTimecard
V1EmployeesApi listCashDrawerShifts GET /v1/{location_id}/cash-drawer-shifts ListCashDrawerShifts
V1EmployeesApi listEmployeeRoles GET /v1/me/roles ListEmployeeRoles
V1EmployeesApi listEmployees GET /v1/me/employees ListEmployees
V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events ListTimecardEvents
V1EmployeesApi listTimecards GET /v1/me/timecards ListTimecards
V1EmployeesApi retrieveCashDrawerShift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} RetrieveCashDrawerShift
V1EmployeesApi retrieveEmployee GET /v1/me/employees/{employee_id} RetrieveEmployee
V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} RetrieveEmployeeRole
V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} RetrieveTimecard
V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} UpdateEmployee
V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} UpdateEmployeeRole
V1EmployeesApi updateTimecard PUT /v1/me/timecards/{timecard_id} UpdateTimecard
V1ItemsApi adjustInventory POST /v1/{location_id}/inventory/{variation_id} AdjustInventory
V1ItemsApi applyFee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} ApplyFee
V1ItemsApi applyModifierList PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} ApplyModifierList
V1ItemsApi createCategory POST /v1/{location_id}/categories CreateCategory
V1ItemsApi createDiscount POST /v1/{location_id}/discounts CreateDiscount
V1ItemsApi createFee POST /v1/{location_id}/fees CreateFee
V1ItemsApi createItem POST /v1/{location_id}/items CreateItem
V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists CreateModifierList
V1ItemsApi createModifierOption POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options CreateModifierOption
V1ItemsApi createPage POST /v1/{location_id}/pages CreatePage
V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations CreateVariation
V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} DeleteCategory
V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} DeleteDiscount
V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} DeleteFee
V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} DeleteItem
V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} DeleteModifierList
V1ItemsApi deleteModifierOption DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} DeleteModifierOption
V1ItemsApi deletePage DELETE /v1/{location_id}/pages/{page_id} DeletePage
V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells DeletePageCell
V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} DeleteVariation
V1ItemsApi listCategories GET /v1/{location_id}/categories ListCategories
V1ItemsApi listDiscounts GET /v1/{location_id}/discounts ListDiscounts
V1ItemsApi listFees GET /v1/{location_id}/fees ListFees
V1ItemsApi listInventory GET /v1/{location_id}/inventory ListInventory
V1ItemsApi listItems GET /v1/{location_id}/items ListItems
V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists ListModifierLists
V1ItemsApi listPages GET /v1/{location_id}/pages ListPages
V1ItemsApi removeFee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} RemoveFee
V1ItemsApi removeModifierList DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} RemoveModifierList
V1ItemsApi retrieveItem GET /v1/{location_id}/items/{item_id} RetrieveItem
V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} RetrieveModifierList
V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} UpdateCategory
V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} UpdateDiscount
V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} UpdateFee
V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} UpdateItem
V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} UpdateModifierList
V1ItemsApi updateModifierOption PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} UpdateModifierOption
V1ItemsApi updatePage PUT /v1/{location_id}/pages/{page_id} UpdatePage
V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells UpdatePageCell
V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} UpdateVariation
V1LocationsApi listLocations GET /v1/me/locations ListLocations
V1LocationsApi retrieveBusiness GET /v1/me RetrieveBusiness
V1TransactionsApi createRefund POST /v1/{location_id}/refunds CreateRefund
V1TransactionsApi listBankAccounts GET /v1/{location_id}/bank-accounts ListBankAccounts
V1TransactionsApi listOrders GET /v1/{location_id}/orders ListOrders
V1TransactionsApi listPayments GET /v1/{location_id}/payments ListPayments
V1TransactionsApi listRefunds GET /v1/{location_id}/refunds ListRefunds
V1TransactionsApi listSettlements GET /v1/{location_id}/settlements ListSettlements
V1TransactionsApi retrieveBankAccount GET /v1/{location_id}/bank-accounts/{bank_account_id} RetrieveBankAccount
V1TransactionsApi retrieveOrder GET /v1/{location_id}/orders/{order_id} RetrieveOrder
V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} RetrievePayment
V1TransactionsApi retrieveSettlement GET /v1/{location_id}/settlements/{settlement_id} RetrieveSettlement
V1TransactionsApi updateOrder PUT /v1/{location_id}/orders/{order_id} UpdateOrder

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

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 response HTTP Headers. They are named as their simple counterpart with a WithHttpInfo suffix. Hence listEmployeeRoles would be called listEmployeeRolesWithHttpInfo. This method returns a CompleteResponse object with the response data deserialized along with a helper to retrieve the token if present.

  2. Use String batchToken = completeResponse.getBatchToken(); to extract the token and proceed to get the following page if a token is present.

Example

// Import classes:
//import .ApiClient;
//import .ApiException;
//import .Configuration;
//import .CompleteResponse;
//import .auth.*;
//import .api.V1EmployeesApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

V1EmployeesApi apiInstance = new V1EmployeesApi();
String order = "order_example"; // String | The order in which employees are listed in the response, based on their created_at field.Default value: ASC
Integer limit = 56; // Integer | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
String batchToken = null;
try {
    do {
        CompleteResponse<List<V1EmployeeRole>> completeResponse = apiInstance.listEmployeeRoles(order, limit, batchToken);
        System.out.println(completeResponse.getData());

        batchToken = completeResponse.getBatchToken();
    } while (batchToken != null);
} catch (ApiException e) {
    System.err.println("Exception when calling V1EmployeesApi#listEmployeeRoles");
    e.printStackTrace();
}

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

[email protected]