API Basics

Get Started with Square APIs

Start building with Square in 7 easy steps.

Step 1: Create a Square account

Square provides collections of APIs that work together to solve a variety of problems, including online payments (eCommerce), in-person payments (point of sale), product management, customer management, and business management.

To work with Square APIs, you must create a Square account or login to an existing account.

Step 2: Create a new application

When you create a new application, Square generates credentials (linked to that application) that you can use to work with Square APIs.

To create a new application:

  1. Open the Application Dashboard.
  2. Click New Application (or Create Your First Application if your account is brand new).
  3. Enter a name for your application.
  4. Agree to Square's Developer Terms of Service and click Create Application.

Step 3: Get to know the application settings pages

Click on the application you created in Step 2 to open the application settings pages. The application settings pages includes multiple pages with different values and settings you may need while developing your application:

  • Credentials — manage application credentials for production and sandbox.
  • OAuth — manage the OAuth workflow for your custom solution.
  • Webhooks — configure and enable webhooks.
  • Reader SDK — configure the Reader SDK for your custom mobile solution.
  • Point of Sale API — configure the Point of Sale API for your custom mobile solution.
  • Apple Pay — configure Apple Pay for Web for eCommerce solutions using the Square Payment Form.
  • Locations — display production and sandbox location IDs for the Square account. Location IDs are listed in the application control panel for convenience.

Step 4: Understand the different application credentials

The application settings pages provide a variety of credentials for accessing Square services. You will need to use different credentials depending on how your application will be used.

Credential Description Use Generation
Personal access token Full-access (unscoped) authorization credential. Grants full production access to the corresponding Square account. Found on the Credentials settings page.
Sandbox token Full access (unscoped) authorization credential. Grants full sandbox access to the corresponding Square account. Found on the Credentials settings page.
Application ID Random, unique ID assigned by Square. Identifies your application in mobile API calls, OAuth requests, and in the Square Payment form. Found on the Credentials settings page.
Application Secret OAuth authentication credential. Authenticates your application identity in OAuth requests. Found on the OAuth settings page.
Repository password Random, unique ID assigned by Square. Authorizes your development environment to access remote repositories that provide the Reader SDK. Found on the Reader SDK settings page.
OAuth token Scoped authorization credential. Grants limited access to a Square account by asking the account owner for explicit permissions. Requested programmatically using the OAuth API.

Step 5: Try it out!

Now we will use your sandbox token and sandbox location ID to process a test credit card payment.

To find your sandbox token and sandbox location ID:

  1. Go to the Application Dashboard.
  2. Click on your application to open the application control panel.
  3. Click on the Credentials tab to find your sandbox token.
  4. Click on the Locations tab to find the Sandbox location ID for "Coffee & Toffee SF".

Now use the tool below to send a Charge request with a test credit card nonce:

  1. Paste your sandbox token in the Sandbox Token field.
  2. Paste a sandbox location ID in the location_id field.
  3. Select "Transactions" from the API dropdown and "Charge" from the Endpoint dropdown.
  4. Update the default JSON block in the Request text area:
    • Set idempotency_key to any unique string, for example TESTKEY123.
    • Set card_nonce to fake-card-nonce-ok.
  5. Click Send Request. The response body will appear as JSON under Response.
Alert
Alert
Alert
Alert
Alert
Alert
Request
{
  "idempotency_key": "",
  "card_nonce": "",
  "reference_id": "RPCE#12345 ",
  "note": "Miscellaneous dog toys",
  "delay_capture": false,
  "shipping_address": {
    "address_line_1": "123 Main St",
    "locality": "San Francisco",
    "administrative_district_level_1": "CA",
    "postal_code": "94114",
    "country": "US"
  },
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "NY",
    "locality": "New York",
    "postal_code": "10003",
    "country": "US"
  },
  "amount_money": {
    "amount": 5000,
    "currency": "USD"
  }
}
This endpoint does not require a request body
Response Alert

  

Step 6: Get to know Square's APIs and SDKs

Square's Developer Platform provides a variety of development tools:

  • Connect v1 API Suite — supports webhooks and employee, role, and timecard management. Payment and item management functionality in the v1 suite is still fully supported but provided primarily for backward compatibility. New applications should use the Connect v2 API Suite for payments and item management.
  • Connect v2 API Suite — supports online payments, order creation for itemized transactions, product catalog management, and customer management.
  • Connect SDKs — simplify development by encapsulating the Connect v1 and Connect v2 API suites. Available for PHP, Node.js, Ruby, Python, Java, and C#.
  • Mobile APIs and SDKs — support in-person payments for mobile web and custom mobile applications.
    • Point of Sale API: Call the Square Point of Sale app from native Android and iOS apps.
    • Reader SDK: Use Square Reader to accept payments in native Android and iOS apps.

Step 7: Start building with Square

Build a custom online payment solution

Take payments securely on your website with full control of the checkout process using the Transactions API and Square Payment Form.

Build a custom point of sale app

Take payments in-person with your own iOS, Android, mobile web app using the Point of Sale API.

Integrate with a pre-built payment solution

Take payments securely on your website with Square's prebuilt eCommerce solution using the Checkout API.

Build a custom integration

Combine Square APIs to manage products and customers, create orders, and track sales across multiple channels.

Ask for help on Stack Overflow or join our Slack channel