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 and familiarize yourself with the directory structure and supporting files.

   cd quickstart

3. Your project is defined by its project object model (POM). Open the pom.xml file in a text editor and replace its contents 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>44.0.0.20250319</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.AsyncSquareClient;
   import com.squareup.square.core.Environment;
   import com.squareup.square.types.Location;
   import com.squareup.square.types.Error;
   import com.squareup.square.core.SquareApiException;
   import com.squareup.square.types.Address;
   
   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();
           }
   
           AsyncSquareClient client = AsyncSquareClient.builder()
               .token(prop.getProperty("SQUARE_ACCESS_TOKEN"))
               .environment(Environment.SANDBOX)
               .build();
   
           client.locations().list()
               .thenAccept(result -> {
                   System.out.println("Location(s) for this account:");
                   result.getLocations().ifPresent(locations -> {
                       for (Location l : locations) {
                           // Build location details safely
                           StringBuilder locationInfo = new StringBuilder();
   
                           // Add ID if present
                           l.getId().ifPresent(id -> locationInfo.append("ID: ").append(id));
   
                           // Add name if present
                           l.getName().ifPresent(name -> 
                               locationInfo.append(locationInfo.length() > 0 ? ", " : "")
                                        .append("Name: ").append(name));
   
                           // Handle address details if present
                           l.getAddress().ifPresent(address -> {
                               // Add address line 1 if present
                               address.getAddressLine1().ifPresent(line1 -> 
                                   locationInfo.append(locationInfo.length() > 0 ? ", " : "")
                                            .append("Address: ").append(line1));
   
                               // Add locality (city) if present
                               address.getLocality().ifPresent(locality -> 
                                   locationInfo.append(locationInfo.length() > 0 ? ", " : "")
                                            .append("City: ").append(locality));
                           });
   
                           // Print the complete location information
                           System.out.println(locationInfo.toString());
                       }
                   });
               })
               .exceptionally(exception -> {
                   if (exception.getCause() instanceof SquareApiException) {
                       SquareApiException apiException = (SquareApiException) exception.getCause();
                       apiException.errors().forEach(error -> {
                           System.out.println("Category: " + error.getCategory());
                           System.out.println("Code: " + error.getCode());
                           System.out.println("Detail: " + error.getDetail());
                       });
                   } else {
                       System.out.println("An unexpected error occurred:");
                       exception.printStackTrace();
                   }
                   return null;
               })
               .join();
       }
   }

2. Save the Quickstart.java file.

   This code does the following:

   • Reads a configuration file that contains your Square Sandbox access token. For more information, see Set your Square credentials.
   • Creates a client object that uses your credentials to authenticate with Square.
   • Calls the list method of the Locations API to retrieve the locations associated with the Square account.
   • If the request is successful, the code prints the location information in 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.

1. Create a new subdirectory in your project (src/main/resources) and 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. Finally, run your Quickstart program:

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