How It Works

The Point of Sale API lets mobile applications open the Square Point of Sale application 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 applications on iOS and Android.

Link to section

Point of Sale API process flow

The following example process flow shows how mobile application code interacts with the Square Point of Sale API:

  1. The seller mobile application determines the total amount to charge a customer.

  2. The seller mobile application packages the transaction information and sends it in a request to the Square Point of Sale application.

  3. The mobile device running the seller mobile application automatically opens the Square Point of Sale application.

  4. The charge amount is pre-populated in the Square Point of Sale application based on the provided transaction information.

  5. The transaction is completed with the Square Point of Sale application checkout flow.

  6. The Square Point of Sale application sends completed transaction information to the provided callback URL.

  7. The device reactivates the seller mobile application to receive and display the transaction results.

    A diagram showing the mobile client to Square server process flow in a Point of Sale API integration.

    If the payment is successful, the Point of Sale application 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.

Link to section

Point of Sale API data model

The seller mobile application 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 (for example, USD).
  • Tender types - The tender types allowed as payment. The selected tender types are displayed by the Square Point of Sale application during payment processing.
  • Callback URL - The callback URL that Square Point of Sale uses to pass results back to the seller mobile application.
  • Application ID - The Square-issued application ID of the seller mobile application.
  • API version - The targeted version of the Square Point of Sale API (for example, v2.0).

The Square Point of Sale API receives a request object with transaction information and opens the Point of Sale application prepopulated with:

  • 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 applications package transaction information and send it to the Square Point of Sale application. The Point of Sale API uses URLs with custom schemes to communicate between mobile web applications and the Square Point of Sale application. Square Point of Sale accepts URLs with the scheme square-commerce-v1 and sends transaction results back to the calling application using the URL scheme.

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