Square Java SDK Quickstart

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.

1. Create a Square account and an application. For more information, see Create an Account and Application.

2. Get a Sandbox access token from the Developer Console. For more information, see Get a personal access token.

3. 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.

1. 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-quickstart

2. After the command completes, go to your new project directory.

   cd ./quickstart

   Familiarize yourself with the directory structure and supporting files.

3. 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>

4. Replace SDK_VERSION_HERE with the latest version of the Square Java SDK:

   <version>42.1.0.20241218</version>

5. When finished, save the pom.xml file.

1. 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();
       }
   }

2. 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:

1. 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=yourSandboxAccessToken

2. Replace yourSandboxAccessToken with your Square Sandbox access token.

3. When finished, save the config.properties file.

1. Run the following command:

   mvn package -DskipTests

   Maven compiles your program into bytecode and prepares it for execution.

2. Run the following command:

   mvn exec:java -Dexec.mainClass="com.square.examples.Quickstart"

3. Verify the result. You should see at least one location (Square creates one location when you create a Square account).

• Set up your Square SDK for a Java Project
• Using the Square Java SDK
• Common Square API Patterns