Point of Sale API Overview
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.
- Mobile Web
Requirements and limitations
Point of Sale API requires:
- An Android or iOS device with the most recent version of Square's Point of Sale app installed
- An activated Square merchant account (for accepting card payments)
- A Square Contactless and Chip Card reader (for accepting EMV and Apple/Android pay)
- A Square Magstripe reader (for accepting magstripe cards)
Point of Sale API does not support:
- Itemized sales
- Square invoices
- In lieu of sandbox mode, Square recommends taking and refunding $1 payments to test your application.
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 this article for details.
How it works
For a merchant using your app, the Point of Sale API payment flow looks like this:
- The merchant uses your app to determine the amount of money to charge a customer.
- The merchant's device quickly switches from your app to Square Point of Sale, where the amount to charge is pre-populated.
- The merchant processes the payment with Square Point of Sale.
- The merchant's device switches back to your app, which receives information about the result of the transaction.
The Point of Sale API is compatible with native iOS and Android apps as well as web apps running in mobile browsers. Native developers should use the open source SDKs published by Square (Android, iOS) to interact with the API. Web developers should refer to the web-specific documentation for their specific platform (Android, iOS).
You will pass Point of Sale API a request containing at a minimum:
- The amount to be charged
- The tender types to accept
- Your Square Application ID
You can also include optional parameters such as:
- A note to be associated with the transaction
- Reference information to be returned to you when your transaction finishes
- A Square customer ID to be associated with the transaction
- Options to configure the Square payment flow
Starting the request will switch control from your app to the Square Point of Sale, where the merchant will complete the transaction using the Point of Sale payment flow. Once the transaction is complete, your app will receive a callback that indicates if the request failed or was successful.
Successful request callbacks will include reference IDs for the transaction that you can use with the Square Connect APIs. Failed request callbacks will include an error code indicating why the request failed. All callbacks will include the reference information you passed, if applicable. You should record the transaction IDs returned to you by the API for future use with Connect APIs (for example: for issuing refunds or cross-referencing past payments).
Your application should keep track of whether a Point of Sale API request has been issued and whether or not a callback has been received. Because of the constraints of app-switching APIs, merchants may leave Square Point of Sale during an API request and return to your app, and it is your responsibility to direct them to return to Square and finish the transaction.
To get started, refer to the guide for your specific platform and technology: