Learn how to quickly set up and test the Square Ruby SDK.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
SDKs and Samples

Square Ruby SDK Quickstart

Learn how to quickly set up and test the Square Ruby SDK.

Link to section
Prepare for the Quickstart

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 Dashboard. For more information, see Make your First API Call.

  3. Install the following:

    • Ruby - Square supports Ruby version 2.7 or later.

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

      • 1
      gem install square.rb

Link to section
Create a project

  1. Open a new terminal window.

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

    • 1
    • 2
        mkdir quickstart
    cd ./quickstart

Link to section
Write code

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

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    require 'square'

client = Square::Client.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:

Link to section
Set your Square credentials

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:

Link to section
Linux or macOS

  • 1
export SQUARE_ACCESS_TOKEN=yourSandboxAccessToken

Link to section
Windows: PowerShell

  • 1
Set-item -Path Env:SQUARE_ACCESS_TOKEN -Value yourSandboxAccessToken

Link to section
Windows: Command shell

  • 1
set SQUARE_ACCESS_TOKEN=yourSandboxAccessToken

Link to section
Run the application

  1. Run the following command:

    • 1
    ruby ./quickstart.rb

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

Link to section
See also

On this page