Learn how to quickly set up and test the Square Java SDK.
Before you begin, you need a Square account and account credentials. You use the Square Sandbox for the Quickstart exercise.
Create a Square account and an application. For more information, see Create an Account and Application.
Get a Sandbox access token from the Developer Console. For more information, see Make your First API Call.
Install the following:
- Oracle Java SE Development Kit - Square supports Java version 8 or later.
- Apache Maven for dependency management. Square supports both Maven and Gradle, but you use Maven in the Quickstart.
Note
If you prefer to skip the following setup steps, download the Square Java SDK Quickstart sample and follow the instructions in the README.
Open a new terminal window. Use the Maven command-line interface (
mvn
) to create a simple project.mvn archetype:generate \ -DinteractiveMode=false \ -DgroupId=com.square.examples \ -DartifactId=quickstart \ -DarchetypeArtifactId=maven-archetype-quickstartAfter the command completes, go to your new project directory.
cd ./quickstartFamiliarize yourself with the directory structure and supporting files.
Your project is defined by its project object model (POM). Open the pom.xml file in a text editor and replace its entire content with the following:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.square.examples</groupId> <artifactId>quickstart</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>quickstart</name> <url>http://maven.apache.org</url> <dependencies> <dependency> <groupId>com.squareup</groupId> <artifactId>square</artifactId> <version>SDK_VERSION_HERE</version> <scope>compile</scope> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>3.0.0</version> <configuration> <mainClass>com.square.examples.Quickstart</mainClass> <cleanupDaemonThreads>false</cleanupDaemonThreads> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.1</version> <configuration> <source>8</source> <target>8</target> </configuration> </plugin> </plugins> </build> </project>Replace SDK_VERSION_HERE with the latest version of the Square Java SDK:
<version>
41.2.0.20241017</version>
When finished, save the pom.xml file.
In your project's src/main/java/com/square/examples subdirectory, create a new file named Quickstart.java with the following content:
package com.square.examples; import java.io.IOException; import java.io.InputStream; import java.util.Properties; import com.squareup.square.*; import com.squareup.square.api.*; import com.squareup.square.authentication.BearerAuthModel; import com.squareup.square.models.*; import com.squareup.square.models.Error; import com.squareup.square.exceptions.*; public class Quickstart { public static void main(String[] args) { InputStream inputStream = Quickstart.class.getResourceAsStream("/config.properties"); Properties prop = new Properties(); try { prop.load(inputStream); } catch (IOException e) { System.out.println("Error reading properties file"); e.printStackTrace(); } SquareClient client = new SquareClient.Builder() .bearerAuthCredentials(new BearerAuthModel.Builder(prop.getProperty("SQUARE_ACCESS_TOKEN")).build()) .environment(Environment.SANDBOX) .build(); LocationsApi locationsApi = client.getLocationsApi(); locationsApi.listLocationsAsync().thenAccept(result -> { System.out.println("Location(s) for this account:"); for (Location l : result.getLocations()) { System.out.printf("%s: %s, %s, %s\n", l.getId(), l.getName(), l.getAddress().getAddressLine1(), l.getAddress().getLocality()); } }).exceptionally(exception -> { try { throw exception.getCause(); } catch (ApiException ae) { for (Error err : ae.getErrors()) { System.out.println(err.getCategory()); System.out.println(err.getCode()); System.out.println(err.getDetail()); } } catch (Throwable t) { t.printStackTrace(); } return null; }).join(); SquareClient.shutdown(); } }Save the Quickstart.java file.
This code does the following:
- Reads a configuration file that contains your Square access token. For more information, see Set your Square credentials.
- Creates a SquareClient object that uses the credentials to authenticate with Square.
- Creates a LocationsApi object that uses the
SquareClient
object to make API calls. - Calls the listLocationsAsync method of the
LocationsApi
object to retrieve the locations associated with the Square account. - If the request is successful, the code prints the location information on the terminal.
The Java code in this Quickstart reads your Square Sandbox access token from a separate configuration file. This helps avoid the use of hardcoded credentials in the code. Do the following:
Create a new subdirectory (src/main/resources) and then, within that subdirectory, create a file named config.properties with the following content:
SQUARE_ACCESS_TOKEN=yourSandboxAccessTokenReplace
yourSandboxAccessToken
with your Square Sandbox access token.When finished, save the config.properties file.
Run the following command:
mvn package -DskipTestsMaven compiles your program into bytecode and prepares it for execution.
Run the following command:
mvn exec:java -Dexec.mainClass="com.square.examples.Quickstart"Verify the result. You should see at least one location (Square creates one location when you create a Square account).