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, shops, and partners can all have associated API keys of the following format:

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

Requests

Request bodies are always a single JSON object. The fields described in this documentation are the keys in this root object and their respective values:

POST /v2/1234:trn:21/refund
Host: api.scanpay.dk
Authorization: Basic czEyMzQ6RmhuSUpWUzJaZ1JpMkIzNUpCSnNlXzZvUUUzUGlPS0ZFS3FQVDItcmk4NTBEdXpvUnNRNUdPTnoyZWdZLXpRWA==
Content-Length: 41

{
    "total": "20 DKK",
    "index": 1
}

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.

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

To get a test account, contact us and let us know what you need it for.