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 control panel

Click on the application you created in Step 2 to open the application control panel. The control panel includes multiple tabs 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.
  • Point of Sale API — configure the Point of Sale API for your mobile custom 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 control panel provides 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 tab of the application control panel.
Sandbox token Full access (unscoped) authorization credential. Grants full sandbox access to the corresponding Square account. Found on the Credentials tab of the application control panel.
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 tab of the application control panel.
Application Secret OAuth authentication credential. Authenticates your application identity in OAuth requests. Found on the OAuth tab of the application control panel.
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": "Miscellanious 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 (iOS and Android) applications.

The Connect v2 API Suite also has a Swagger specification available on Github. If your preferred language is not supported by the official Connect SDKs, you can use the Swagger specification to generate custom client libraries. See Generating client libraries and other tools with Swagger for more information.

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