Introduction

The CoolPay 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:

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 three 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 – first warning
  • v08: Deprecated version – last warning

Access and Security

Any and all communication is encrypted using a 4096 Bit SHA256 RSA certificate issued by Comodo using the protocols TLS 1.0, 1.1 & 1.2.

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 CoolPay. 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 CoolPay API recognizes four HTTP request methods:

MethodDescription
GETGet a resource or list of resources
POSTCreate a resource
PUTReplace a resource
PATCHUpdate a resource
DELETEDelete a resource

Headers

MethodDescription
HostThe domain name of the server
AuthorizationHTTP Basic authentication
Accept-VersionThe desired version of the API
AcceptContent-Types that are acceptable – currently only application/json is available for non-static resources
Content-TypeThe mime type of the body of the request (used with POST and PUT requests)
Content-LengthLength (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.coolpay.com
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.coolpay.com
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 CoolPay API:

HTTP StatusDescription
200 OKStandard 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 CreatedA new resource was created and a response body containing a representation of the new resource is being returned.
202 AcceptedRequest was accepted but not yet processed. A Location header containing the canonical URI for the newly created resource should also be returned.
400 Bad RequestThe 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 UnauthorizedSimilar 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 requiredYou either need to create a or upgrade your payment plan.
403 ForbiddenThe server recognized your credentials, but you do not possess authorization to perform this request.
404 Not FoundThe requested resource could not be found
405 Method Not AllowedA 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 AcceptableThe requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
409 ConflictA 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).
500 Internal Server ErrorThe server encountered an unexpected condition which prevented it from fulfilling the request.

Headers

HeaderDescription
Content-TypeThe media type of the response body
Content-LengthLength (in bytes) of the response message body
LocationCanonical 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 messageerrors 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.

Opret bruger