Introduction

The QuickPay API is based on the principles of Representational State Transfer (REST) allowing clients to create, view, modify and delete resources using standard HTTP request methods.

Recommended reading:

• HTTP: http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
• Headers: http://en.wikipedia.org/wiki/List_of_HTTP_headers
  • Basic access authentication: http://en.wikipedia.org/wiki/Basic_access_authentication
  • Status codes: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
• REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
• JSON: http://en.wikipedia.org/wiki/JSON

The QuickPay API is purposely the service upon which everything else in QuickPay is built (we eat our own dog food).

About versioning

Over time new features will come along and others will be removed. To foresee and avoid potential compatibility issues, the API handles this by having multiple versions available at the same time. How to specify the desired version in the HTTP request is explained in detail later on.

There is however a limit in terms of backward compability and at any time only the two newest versions will be available. In addition a be beta/preview version might also be available. This example demostrates the versions and their lifecycle:

• v11b: Public beta/preview version
• v10: Latest version
• v09: Deprecated version

Access and Security

Any and all communication is encrypted using a TLS.

To interact with our API you will need to create a user. With this user you can create multiple merchant accounts or be connected to existing merchant accounts.

Authentication is done by using HTTP Basic Auth and you will need valid credentials from your account at QuickPay. It is possible to create a seperate and restricted user account for API usage – in fact, we do not only encourage you to do so… your new merchant account automatically comes with a restricted user “Payment Window”.

The HTTP Request

URI

The request URI identifies the resource we want to handle. See the complete list over resources in the sidebar to the left.

Method

Request methods defines the action we wish to perform on a resource. The QuickPay API recognizes five HTTP request methods:

Headers

Body

Data in the request body is only considered if request method is POST or PUT. Here are some examples:

To update a resource:

PUT /resource/<Identifier> HTTP/1.1
Host: api.quickpay.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept-Version: v10
Accept: application/json
key1=value1&key2=value2

To get a resource:

GET /resource/<Identifier> HTTP/1.1
Host: api.quickpay.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept-Version: v10
Accept: application/json

The HTTP Responses

Status

The HTTP response status line contains a status code. This code is used to identify wether the request went well or if an error occurred. If indeed something went wrong in processing of the request, the status code will also tell something about the type of error.

The following status codes are defined in the QuickPay API:

Headers

Body

The response body for any non-static resource requests will contain a JSON document. The JSON-encoded data will either be a hash or a list of hashes. Here are some examples:

Response for a successful request for a single resource:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: nnn

{
  "key1": "value1",
  "key2": "value2"
}

Response for a successful request for a list of resources:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: nnn

[
  {
    "key1": "value1",
    "key2": "value2"
  },
  {
    "key1": "value1",
    "key2": "value2"
  }
]

If processing of a request fails the response may look like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
Content-Length: nnn

{
  "message": "Validation error",
  "errors": {
    "key1": ["is required", "must be at least 5 chars"]
  },
  "error_code": null
}

All error responses have message, errors and error_code keys, but errors and error_code might be NULL.

Static resources

If the resource is a static resource the “Content-Type” header will reflect the media type in question – eg. “application/png”, “text/css” etc. The response body will contain the raw resource data or will be empty on errors.

Pagination

The recommended way to travese a list of resource is to use the information provided in the Link header of a API request. The Link header includes a link that can be used to request the next “page” or batch of the resource. The link uses the page_key parameter.

Example

A default GET /payments request responds with the first 20 payments. You can specify the number of payments in the response by using the page_size parameter.

To navigate through pages you must look at the information located in the Link header of the API request.

Example of link header of a GET /payments request:

Link: <https://api.quickpay.net/payments?page_key=&timestamp=created_at&page_size=20&sort_by=id&sort_dir=desc>; rel="first",
<https://api.quickpay.net/payments?page_key=130889993&timestamp=created_at&page_size=20&sort_by=id&sort_dir=desc>; rel="next"

The link with rel="next" specifies how to request the next page of payments. In this example requesting https://api.quickpay.net/payments?page_key=130889993&timestamp=created_at&page_size=20&sort_by=id&sort_dir=desc will provide the next 20 payments.