Edit

API Overview

Our API is designed around a simple principle: when objects are created or modified in our system, you receive a notification in the form of a ping, which tells you there's new data ready to fetch using the seq request. These objects are referred to using URIs in our API:

URIs

All API requests are made to whole or partial URIs. A URI is built up of 4 components: 

shopid:db#id@rev
  • shopid is the ID associated with the shop. It can be found in the dashboard.
  • db is which database the object is located in.
  • id is the ID of the entry in that database.
  • rev is the revision (version) of the object.

No API request uses a full URI as no request refers to a specific revision of an object. Similarly, some API requests only refer to databases and not specific objects. Since # can be very annoying to encode in an HTTP request, we allow the use of : instead, so all API request URLs follow this scheme: 

https://api.scanpay.dk/v2/{shopid}:{db}/{action}
https://api.scanpay.dk/v2/{shopid}:{db}:{id}/{action}

Authentication

All API requests require HTTP Basic authentication using an API key as the credential: 

Authorization: Basic Base64Encode("{apikey}")

API keys

All actions, be they performed through the API documented here or the dashboard, are done by traceable API keys. Users and shops can both have associated API keys of the following format: 

u{userid}:{keyid}:randomness
s{shopid}:{keyid}:randomness
  • userid is the ID of the user the key was issued by.
  • shopid is the ID of the shop the key was issued to.
  • keyid is the immutable unique ID of the key itself. It is only unique to that given user or shop, not globally.

Responses

Successful requests always have an HTTP response code of 200 and a JSON object in the response body. On error, responses always have a non-200 code and a textual error message both as the HTTP response message and as a singular line in the response body: 

HTTP/1.1 403 invalid apikey

Content-Length: 15
invalid apikey

Environments

We have two distinct environments: a production and a testing environment. They are in no way connected and an account on one confers no access to the other. The test environment is for developing integrations and accounts on the testing environment can only be created manually by us. To get one, contact us.

  • Production Endpoint: api.scanpay.dk
  • Testing Endpoint: api.scanpay.dev