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 Dashboard. 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.
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>
38.1.0.20240320</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.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() .accessToken(prop.getProperty("SQUARE_ACCESS_TOKEN")) .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).