Square Ruby SDK Quickstart

Learn how to quickly set up and test the Square Ruby 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.

2. Get a Sandbox access token from the Developer Console.

3. Install the following:

   • Ruby - Square supports Ruby version 3.1 or later.

   • Square Ruby SDK - To install it, use the gem command:

     gem install square.rb

1. Open a new terminal window. Create a new directory for your project, and then go to that directory.

   mkdir quickstart
   cd ./quickstart

2. Set your square credentials in an .env file. In your project directory, create a new file named .env with the following content, replacing yourSandboxAccessToken with your Square Sandbox access token:

   SQUARE_ACCESS_TOKEN=yourSandboxAccessToken

1. In your project directory, create a new file named quickstart.rb with the following content:

   require 'square'
   
   client = Square::Client.new(
     token: ENV['SQUARE_ACCESS_TOKEN'],
     base_url: Square::Environment::SANDBOX
   )
   
   begin
     result = client.locations.list
   
     if result.locations
       result.locations.each do |location|
         printf("%s: %s, %s, %s\n",
                location.id,
                location.name,
                location.address&.address_line_1,
                location.address&.locality)
       end
     end
   
   rescue => e
     warn "Error: #{e.message}"
     if e.respond_to?(:errors) && e.errors
       e.errors.each do |error|
         warn error.category
         warn error.code
         warn error.detail
       end
     end
   end

2. Save the quickstart.rb file.

   This code does the following:

   • Loads the environment file containing your Square access token.
   • Creates a new client object instance with your Square access token.
   • Calls the locations.list method on the client object.
   • If the request is successful, the code prints the location information on the terminal.

1. Run the following command:

   ruby ./quickstart.rb

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