DocumentationManage Apps

Connect API v2 released (2016-03)

Version 2 of the Square Connect API is now available. Connect v2 provides the following new features:

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.

Release FAQ

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 https://connect.squareup.com.

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).

Dates. In v2, all dates you provide must conform to RFC 3339. An RFC 3339-compliant date is effectively an ISO 8601-compliant date that omits no optional components besides fractional seconds.

For example, 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 cursor 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 sort_order.

In v1, corresponding endpoints (such as List Payments) list results in oldest-first order by default. The parameter to change this behavior is called order.

Error format. In v2, endpoints include an errors array in their response body if any errors occured during the corresponding request. Each Error object 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.