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

   • Ruby - Square supports Ruby version 2.7 or later.

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

     gem install square.rb

1. Open a new terminal window.

2. Create a new directory for your project, and then go to that directory.

       mkdir quickstart
       cd ./quickstart

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

   require 'square'
   include Square
   
   client = Square::Client.new(
     bearer_auth_credentials: BearerAuthCredentials.new(
       access_token: ENV.fetch('SQUARE_ACCESS_TOKEN')
     ),
     environment: 'sandbox',
     timeout: 1
   )
   
   result = client.locations.list_locations
   
   if result.success?
     result.data.locations.each do |location|
       printf("%s: %s, %s, %s\n",
              location[:id],
              location[:name],
              location[:address][:address_line_1],
              location[:address][:locality])
     end
   
   elsif result.error?
     result.errors.each do |error|
       warn error[:category]
       warn error[:code]
       warn error[:detail]
     end
   end

2. Save the quickstart.rb file.

   This code does the following:

   • Creates a new Square::Client instance with your Square access token. For more information, see Set your Square credentials.
   • Calls the list_locations method on the client.locations object.
   • If the request is successful, the code prints the location information on the terminal.

The Ruby code in this Quickstart reads your Square Sandbox access token from the SQUARE_ACCESS_TOKEN environment variable. This helps avoid the use of hardcoded credentials in the code.

For the following commands, replace yourSandboxAccessToken with your Square Sandbox access token:

export SQUARE_ACCESS_TOKEN=yourSandboxAccessToken

Set-item -Path Env:SQUARE_ACCESS_TOKEN -Value yourSandboxAccessToken

set SQUARE_ACCESS_TOKEN=yourSandboxAccessToken

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

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