2016-03-30 Changelog

Point of Sale API
Connect v2
Link to section

Details

  • Version 2 of the Square Connect API (Connect v2) is now available. Connect v2 provides the following new features:
    • Accepting eCommerce payments from a webpage with a secure, customizable web form.
    • Managing customer data for online buyers, including cards on file.
  • The Square Point of Sale API is also now generally available. The Point of Sale API lets you deep-link into Square Point of Sale from an iOS native or web app to process in-person payments with Square.
Link to section

Availability

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.

Link to section

Pricing

  • For online (eCommerce) 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 Point of Sale with the Point of Sale API, standard Square fees apply. See this article for details of Square's fees.
Link to section

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

Link to section

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.

Link to section

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.
  • OAuth API endpoints. OAuth API endpoints are unchanged, as is the format for the Authorization header you provide in your requests.
  • Required headers. All Connect API endpoints require the following headers:
    Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Accept: application/json
Link to section

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 v1, all dates must conform to the less strict ISO 8601. 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.
  • 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 ListPayments) 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 occurred during the corresponding request. Each Error object included in the array has a consistent format. In v1, only one error is ever returned in a single response, and the errors have a different format from v2 errors.