Take Payments

Point of Sale API Overview

Open the Square Point of Sale app from a custom mobile application to process in-person payments using Square hardware.

The Point of Sale API lets mobile applications open the Square Point of Sale app to process in-person payments using Square hardware. Developers can use the Point of Sale API to build customized point-of-sale solutions or any other application that requires payments, without worrying about hardware integrations or PCI compliance. The Point of Sale API is available for native and web apps on iOS and Android.

Requirements and limitations

The Point of Sale API requires an Android or iOS device with the most recent version of Square's Point of Sale app installed.

Point of Sale API does not support:

Processing card payments with the Point of Sale API requires:

  • An activated Square merchant account (for accepting card payments).
  • A Square Reader for accepting card payments.

Processing fees for transactions initiated with the Point of Sale API are identical to fees for transactions initiated directly from Square Point of Sale. See What are Square's Fees? for details.

How to use it — the Point of Sale API Data Model

The merchant mobile app needs to package a request object with the following required information and send it to the Square Point of Sale API.

  • Total amount — The total transaction amount represented in the smallest unit of the supplied currency. For example a value of 100 corresponds to 1 USD.
  • Currency code — The currency code of the transaction, e.g., USD.
  • Tender types — The tender types allowed as payment. The selected tender types are displayed by the Square Point of Sale app during payment processing.
  • Callback URL — The callback URI that Square Point of Sale will use to pass results back to the merchant mobile app.
  • Application ID — The Square-issued application ID of the merchant mobile app.
  • API version — The targeted version of the Square Point of Sale API, e.g., v2.0.

The Square Point of Sale API receives a request object with transaction information and opens the Point of Sale app pre-populated:

  • A note to be associated with the transaction.
  • Reference information that is returned when the transaction completes.
  • A Square customer ID to be associated with the transaction.

Mobile apps package transaction information and send it to the Square Point of Sale app. The Point of Sale API uses URLs with custom schemes to communicate between mobile web apps and the Square Point of Sale app. Square Point of Sale accepts URLs with the scheme square-commerce-v1 and sends transaction results back to the calling app using the URL scheme.

Mobile web apps open the Point of Sale API by opening a URL with parameters that contain the required information.

How it works — the Point of Sale API process flow

Here is an example process flow for how a mobile app code interacts with the Square Point of Sale API.

  1. The merchant mobile app determines the total amount to charge a customer.
  2. The merchant mobile app packages the transaction information and sends it in a request to the Square Point of Sale app.
  3. The mobile device running the merchant mobile app automatically opens the Square Point of Sale app.
  4. The charge amount is pre-populated in the Square Point of Sale app based on the provided transaction information.
  5. The transaction is completed with the Square Point of Sale app checkout flow.
  6. The Square Point of Sale app sends completed transaction information to the provided callback URL.
  7. The device reactivates the merchant mobile app to receive and display the transaction results.

If the payment is successful, the Point of Sale app response includes a transaction ID and tender IDs that can be used with other Square Connect APIs to pull more information or issue refunds at a later date. Failed or canceled payment results include an error code indicating why the request failed. All callbacks include any reference information packaged with the original checkout flow request.

Android Setup Guide

Build Android solutions with Point of Sale API.

iOS Setup Guide

Build iOS solutions with Point of Sale API.

Mobile Web Setup Guide

Build mobile web solutions with Point of Sale API.

Ask for help on Stack Overflow or join our Slack channel