square / square-java-sdk

Java client library for the Square API

Square Java SDK

Use this library to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.

• Requirements
• Installation
• Quickstart
• Usage
• Tests
• SDK Reference
• Deprecated APIs

Requirements

Use of the Square Java SDK requires:

• Java 8 or higher
• Maven or Gradle

Installation

For more information, see Set Up Your Square SDK for a Java Project.

Quickstart

For more information, see Square Java SDK Quickstart.

Usage

For more information, see Using the Square Java SDK.

Tests

First, clone the repo locally and cd into the directory.

git clone https://github.com/square/square-java-sdk.git
cd square-java-sdk

Before running the tests, find a sandbox token in your Developer Dashboard and set a SQUARE_ACCESS_TOKEN environment variable.

export SQUARE_ENVIRONMENT=sandbox
export SQUARE_ACCESS_TOKEN="YOUR_SANDBOX_ACCESS_TOKEN"

If you are using Maven, run the tests with below command

mvn test

SDK Reference

Payments

• Payments
• Refunds
• Disputes
• Checkout
• Apple Pay
• Cards
• Payouts

Terminal

• Terminal

Orders

• Orders
• Order Custom Attributes

Subscriptions

• Subscriptions

Invoices

• Invoices

Items

• Catalog
• Inventory

Customers

• Customers
• Customer Custom Attributes
• Customer Groups
• Customer Segments

Loyalty

• Loyalty

Gift Cards

• Gift Cards
• Gift Card Activities

Bookings

• Bookings
• Booking Custom Attributes

Business

• Merchants
• Merchant Custom Attributes
• Locations
• Location Custom Attributes
• Devices
• Cash Drawers
• Vendors

Team

• Team
• Labor

Financials

• Bank Accounts

Online

• Sites
• Snippets

Authorization

• Mobile Authorization
• OAuth

Webhook Subscriptions

• Webhook Subscriptions

Deprecated APIs

The following Square APIs are deprecated:

• Employees - replaced by the Team API. For more information, see Migrate from the Employees API.

• Transactions - replaced by the Orders and Payments APIs. For more information, see Migrate from the Transactions API.

Usage Notes for V1 Transactions

The Square API supersedes the legacy Connect V1 APIs. Square strongly discourages using Connect V1 for most use cases. However, you must still use Connect V1 for listing settlements and listing payments. For more information, see When to Use Connect V1.

In the Square Java SDK, the V1TransactionsApi class provides ListSettlements and ListPayments for accessing these Connect V1 endpoints. However, Square has identified an issue that prevents these methods from returning results. There is no workaround for this issue.

If you need to use List settlements or List payments, you should send HTTP GET requests directly to these Connect V1 endpoints. The response body consists of a JSON list of objects, which you can process as needed.

You'll also need to provide logic to handle paginated results. For more information, see Pagination in Connect V1.