API Introduction

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:

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:

Method Description
GET Get a resource or list of resources
POST Create a resource
PUT Replace a resource
PATCH Update a resource
DELETE Delete a resource

Headers

Method Description
Host The domain name of the server
Authorization HTTP Basic authentication
Accept-Version The desired version of the API
Accept Content-Types that are acceptable – currently only application/json is available for non-static resources
Content-Type The mime type of the body of the request (used with POST and PUT requests)
Content-Length Length (in bytes) of the response message body (used with POST and PUT requests)

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:

HTTP Status Description
200 OK Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.
201 Created A new resource was created and a response body containing a representation of the new resource is being returned.
202 Accepted Request was accepted but not yet processed. A Location header containing the canonical URI for the newly created resource should also be returned.
400 Bad Request The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
401 Unauthorized Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
402 Payment required You either need to create a or upgrade your payment plan.
403 Forbidden The server recognized your credentials, but you do not possess authorization to perform this request.
404 Not Found The requested resource could not be found
405 Method Not Allowed A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
406 Not Acceptable The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
409 Conflict A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource).
429 Too Many 4XX Requests The HTTP 429 Too Many 4XX Requests response status code indicates the user has sent too many requests in a given amount of time resulting in a 4XX response. A Retry-After header is included to this response indicating how long to wait before making a new request.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Headers

Header Description
Content-Type The media type of the response body
Content-Length Length (in bytes) of the response message body
Location Canonical URI of a newly created resource – if applicable

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.

Related Articles