Point of Sale API

How It Works

A deeper look at the Point of Sale API

Android
iOS
UI

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.

Point of Sale API process flow
Permalink Get a link to this section

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.

process-flow

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.

Point of Sale API Data model
Permalink Get a link to this section

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.