DocumentationManage Apps

Square APIs: Getting Started

Square provides a collection of APIs to help you build integrations for a wide range of merchant use cases. The most common use cases are:

E-commerce. Merchants can accept online payments with a secure, customizable form they embed on their website. They can also issue refunds for previously processed payments.

In-person commerce. Custom iOS and Android point-of-sale apps can use the Square Register API to process payments securely with Square hardware.

Reporting. Merchants can download the details of their transaction and deposit history, along with their item and inventory information.

Employee management. Business owners can track employee hours and set employee permissions for certain activities, like issuing refunds in Square Register.

Complete the steps in this article to get up and running, and to familiarize yourself with all of Square's APIs. Please note that using Square APIs requires experience with programming.

Step 1: Create a Square account

Square developer accounts are the same as Square merchant accounts. If you already have a Square account you're all set.

If you don't already have a Square account, create one to start using the API.

If you're planning to use Square APIs to process card payments, visit squareup.com/activate after you create your account to ensure your account is enabled for payment processing. Otherwise, if you use a non-sandbox API that requires payments activation, you may get error responses that you must activate.

Step 2: Register an application with Square

Now that you have a Square account, visit https://connect.squareup.com/apps and sign in.

This is your application dashboard. It's where you register new applications, change your application settings, and find all of your application credentials.

To register your first application:

  1. Click New Application.
  2. Enter a name for your application and click Create App. (Note that your application name can't include the word Square.)

As soon as your application is created, the control panel for it appears. The control panel consists of four tabs (Credentials, OAuth, Webhooks, and Register API), each with multiple sections.

Step 3: Learn about application credentials

The Credentials tab of your application's control panel includes a lot of different credentials that can be tricky to keep straight. Here's a quick rundown:

Personal Access Token

This special token gives you full API access to your own Square account. When you send HTTPS requests to Square API endpoints, you include this value in a header to identify yourself.

If you're building an application just for yourself, this is the only access token you'll ever need to use.

Application ID

This is your application's unique ID. It's used in a couple places:

  • If you're building an application that other merchants will use, you'll specify this value during the OAuth flow (discussed later).
  • If you're using the e-commerce API, you'll provide this value when you embed the secure payment form on your website.

Application Secret

If you're building an application that other merchants will use, you provide this value during the OAuth flow to confirm your application's identity.

As its name suggests, this value is a secret! If you think it's been compromised, you can click Show Secret and then Replace Secret in the application control panel to replace it.

Sandbox Application ID and Access Token

The e-commerce API provides a sandbox that lets you try out processing credit card payments without actually moving any money.

To process e-commerce payments in sandbox mode, you provide these credentials anywhere you would typically provide your standard Application ID and Personal Access Token.

Step 4: Send your first HTTPS request

Now that you have your application credentials, you can start communicating with Square APIs! Let's start with a simple curl command.

Paste the following into a terminal and replace PERSONAL_ACCESS_TOKEN with your personal access token:

curl -H "Authorization: Bearer PERSONAL_ACCESS_TOKEN" https://connect.squareup.com/v2/locations

When the command completes, it prints JSON output representing the basic details for all of your Square business' locations. Its structure resembles the following:

{
  "locations": [
    {
      "id": "CBASEDqu0eR0gRyr6d4TArPMZyk",
      "name": "Coffee & Toffee SF",
      "address": {
        "address_line_1": "1455 Market Street",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING"
      ]
    }
  ]
}

Nice work! You've successfully sent a request to the Square Connect API's ListLocations endpoint.

Step 5: Send an HTTPS request from code

A curl command is a nice start, but let's see what that same command looks like from code.

Create a new blank text file, listlocations.py.

Paste the following into listlocations.py and replace REPLACE_ME with your personal access token:

#!/usr/bin/python
import httplib, urllib, json

# All requests to the Square Connect API require an access token in an
# Authorization header. Specify your application's personal access token here
# (available from https://connect.squareup.com/apps)
access_token = 'REPLACE_ME'

# In addition to an Authorization header, requests to the Connect API should
# include the indicated Accept and Content-Type headers.
request_headers = {'Authorization': 'Bearer ' + access_token,
                   'Accept':        'application/json',
                   'Content-Type':  'application/json'}

# Send a GET request to the ListLocations endpoint and obtain the response.
connection = httplib.HTTPSConnection('connect.squareup.com')
request_path = '/v2/locations'
connection.request('GET', request_path, '', request_headers)
response = connection.getresponse()

# Convert the returned JSON body into an array of locations you can work with.
locations = json.loads(response.read())

# Pretty-print the locations array.
print json.dumps(locations, indent=2, separators=(',',': '))

This example is in Python because it's easy to read and run, but you can of course communicate with Square API endpoints from any programming language.

Run the sample from the command line with the following command:

python listlocations.py

The sample will print the same JSON output that your curl command did in Step 4: Send your first HTTPS request.

Step 6: Pick an HTTPS library

No matter what you're building, your application is probably going to be communicating with Square API endpoints over HTTPS. Before you begin development, you should pick an HTTPS library to work with.

For certain languages, Square provides client libraries that make it easy to communicate with API endpoints. (Note that these client libraries currently only support Connect API version 2 endpoints. If you will use version 1 endpoints as well, you should stick with a different library for now.)

All common programming languages provide at least one built-in library for sending HTTPS requests. Most languages also have one or more popular libraries that are developed by a third party.

If this is your first time working with HTTPS requests, the Unirest suite of libraries is recommended. It is well documented and easy to use.

LanguageBuilt-in HTTPS libraryExternal HTTPS librariesSquare client library
PHPcURLUnirestsquare/connect
RubyNet::HTTPUnirest, Faradaysquare_connect
PythonhttplibUnirest, Requestssquareconnect
.NETSystem.NetUnirest, RestSharpSquare.Connect
Objective-C (iOS and OS X)URL loading systemUnirest, AFNetworking
Java (including Android)HTTPURLConnectionUnirest, OkHttp
Node.jshttpUnirest, Request
Gonet/http

It's also recommended that you use an HTTPS request tool (such as Postman or Paw) to help you quickly and easily test out requests to API endpoints during development.

Generating client libraries from Swagger (advanced)

Version 2 of the Connect API is defined with the Swagger specification. The definition is available on Github. You can use this definition to generate custom client libraries, and to simplify other development tasks.

See Generating client libraries and other tools with Swagger for more information.

Step 7: Learn more about the APIs you want to use

You're ready to begin diving into whichever Square APIs fit your use case. Here's a rundown of the APIs Square provides:

OAuth API

If you're using any of the APIs listed below to develop an application for other merchants to use, you use the OAuth API to let those merchants authorize your application to act on their behalf.

When a merchant completes the OAuth flow for your app, you generate an access token for them. If you use this access token wherever you've previously used your personal access token, API requests apply to that merchant's account instead of to yours.

To learn all about using the OAuth API, see OAuth Overview.

Code samples for the OAuth flow are available on Github.

E-commerce API

The e-commerce API consists of a few different components:

  • A Javascript library that you include on your website to embed a secure payment form
  • An HTTPS endpoint (called Charge) that you use to initiate a transaction from your back-end server after a buyer enters their card details into the payment form
  • Additional HTTPS endpoints for initiating refunds, saving customer information, and other actions related to e-commerce

All HTTPS endpoints related to e-commerce are part of Square Connect version 2. Be sure to read the API conventions to learn the details of interacting with these endpoints.

To learn the basics of using the e-commerce API, see E-commerce Overview.

Register API (in-person payments)

The Register API lets your Android or iOS app open the Square Register app to process in-person payments with Square hardware.

If you're developing a custom point-of-sale app, this is the API for you. To learn the basics of using the Register API, see Register API Overview.

Reporting and employee management APIs

Currently, most of Square's reporting and employee management HTTPS endpoints are part of Square Connect version 1. Be sure to read the API conventions to learn the details of interacting with these endpoints.

Code samples for item management and transaction reporting are available on Github.