Connect API v2 released (2016-03)
Version 2 of the Square Connect API is now available. Connect v2 provides the following new features:
- Accepting e-commerce payments from a webpage with a secure, customizable web form
- Managing customer data for online buyers, including cards on file
The Square Register API is also now generally available. The Register API lets you deep-link into Square Register from an iOS native or web app to process in-person payments with Square.
What countries are Square APIs available in?
Currently, Square APIs are available only to developers in the United States and Canada. We are working to make them available in additional countries soon.
What is the pricing for payments processed with Square APIs?
For online payments accepted with Connect v2, the Square processing fee is 2.9% + 30 cents. This is the only fee assessed by Square for the transaction.
For in-person payments accepted via Square Register with the Register API, standard Square fees apply. See this article for details of Square's fees.
Do I need to create a new Connect API application to use Connect v2 endpoints?
Only if you created your application on the application dashboard before 16 Feburary 2016. Applications created on or after 16 February can use Connect v2 endpoints.
If you created your application before 16 February, create a new application in the application dashboard.
Do I need to switch my existing application over to use Connect v2 instead of Connect v1?
No. In fact, a significant number of Connect v1 endpoints are not yet available in v2. An application can communicate with endpoints from both versions.
See the primary FAQ for a summary of which actions are currently supported in v2.
Which conventions from v1 carry over to v2?
Endpoint base URL. All Connect API endpoints are hosted from
Parameter formats. GET and DELETE requests expect parameters in the query string of the URL, whereas POST and PUT requests expect them in the body of the request.
Required headers. All Connect API endpoints require the following headers:
Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Accept: application/json
OAuth API endpoints. OAuth API endpoints are unchanged, as is the format for the
Authorization header you provide in your requests.
Which conventions in v2 differ from v1?
Monetary amounts. All monetary amounts returned by v2 endpoints are positive.
In v1, monetary amounts are negative if they represent money being paid by a merchant (such as a Square processing fee).
2016-01-15T00:00:00Z is a valid ISO 8601 date and a valid RFC
3339 date, whereas
2016-01-15 is valid ISO 8601 but invalid RFC 3339.
In v1, all dates must conform to the less strict ISO 8601.
Pagination. In v2, endpoints that paginate their results return a
field in their response body, which you can provide in the query string of a followup
request to get the next set of results.
In v1, pagination information is instead provided in the
Link response header.
Default sort order. In v2, endpoints that return date-sorted results (such as ListTransactions) list results
in newest-first order by default. Additionally, the parameter to change this
behavior is called
In v1, corresponding endpoints (such as List
Payments) list results in oldest-first order by default. The parameter to
change this behavior is called
Error format. In v2, endpoints include an
errors array in their response
body if any errors occured during the corresponding request. Each
included in the array has a consistent format, described here.
In v1, only one error is ever returned in a single response, and the errors have a different format from v2 errors. The v1 format is described here.