POS API (v2)

Download OpenAPI specification:Download

This document is a technical description of the API for Storebox. The Storebox API is the programming interface for Storebox.

Storebox is a website, where customers’ sign up, and register various user ID’s which can be used to identify their purchases. The customer can be identified by different user ID types, including msisdn (phone number), email address and (payment) card number (PAN).

You can use the API to integrate your backend system to Storebox, enabling you to send receipts generated in your system to Storebox with information identifying your customer, thereby making the receipt available to your customers through Storebox websites. The receipt service is offered in numerous countries with local websites in the Nordic region and an international website for all other countries.

The intended audience for this documentation is technicians developing a system integration to Storebox.

The standard interface described is based on the HTTP protocol, REST web service architecture and JSON data interchange format. A basic understanding of these technologies is expected of the reader.

Integration with POS

It is possible to identify the customers by a (payment) card inserted in the payment terminal at the POI, used in the payment transaction. It is technically possible, because the payment terminal can generate a token of the card number. This token is made using a "hashing algorithm", which is an irreversible mathematical function generating a unique token, from which the real card number cannot be extracted.

This means that storing and transmitting the token through your system does NOT require your system to be PCI-DSS compliant.

The token is transferred to the cashier system/POS as part of the transaction, you can then store this as part of the transaction with the receipt data and use this as userId when sending the receipt data to storebox.com as described below.

Payment terminals

To support the token solution for identifying card number, the payment terminals must be equipped with special software and encryption keys from Storebox in corporation with the terminal supplier. The list of supported terminals is expanding, currently integration is possible with:

  • Point: Cashier register integrated terminals (Xenta and Yomani)
  • Nets Merchant Solutions: Cashier register integrated terminals with either PSAM or Viking software
  • PayEx: Please contact Storebox if in doubt if your terminals are ready for integration.

End user

The end user signs up on the storebox.com website or Storebox app. The website is available on https://www.storebox.com and app on the following locations

Receipt formats

Storebox JSON

The standard receipt format is JSON as defined in the documentation. The format can contain an embedded PDF, but structured data is still required to display the receipt in a uniform format on the Storebox website and app.

ARTS POSLog

ARTS POSLog version 6.0 is supported by the POS API.

To use ARTS POSLog the following content type has to be set when uploading the receipt.

Content-Type: application/x.arts.poslog.v6

As explained in this document, there are different ways of identifying the end user by payment card, phone number, etc.

ARTS POSLog does not support this identification in the actual receipt data, so identification is set through a HTTP header called X-Storebox-userid. The format is <type>=<value> if multiple ids are provided they are separated by “;”. For example

X-Storebox-userid: pan=foobar;msisdn=4511223344

The type and value are explained in the receipt model.

Storebox Download JSON

In some situations the receipt might be available on an external service like Azure Blob Storage or AWS S3.

It is possible for the POS API to fetch the receipt from there and process that receipt.

Instead of uploading a new receipt, a receipt reference is used which has the following format

{
  "provider": "<provider>",
  "contentType": "<content-type>",
  "params": {
    "<key1>": "<value1>",
    "<key2>": "<value2>"
  }
}

provider is the hosting provider. Currently only Azure Blob Storage is supported. contentType is the content type of the stored receipt, for example if it is in ARTS POSLog. paramsare specific for provider.

To use the reference format the following Content-Type has to be set when calling receipt upload.

Content-Type: application/vnd.storebox.receipt.download+json

Azure example

{
  "provider": "azure",
  "contentType": "application/x.arts.poslog.v6",
  "params": {
    "name": "20170618_213244363-110805-25926",
    "uri": "https://example.blob.core.windows.net/example?sv=2015-04-05&sr=c&sig=validsignature&st=2017-06-07T09%3A24%3A30Z&se=2027-06-07T09%3A29%3A30Z&sp=rw"
  }
}

Environments

In the production environment, only production tokens are created. This means that test terminals cannot be used.

The same is true for the test system where only test tokens are generated, so only test terminals work.

When using the test system, the receipts will be available on test.storebox.com. This website works as the production website, so users can be created, and payment card added.

Resends

The POS API will ignore duplicate receipts. A receipt is defined as a duplicate if the checksum is the same as an existing receipt. Changing receipt id will not make the receipt different, however added a newline will.

This allows interation to message queues that cannot guarantee single delivery.

Authentication

basicAuth

HTTP Basic Authentication is supported using the delivered username and the API key. For each API call HTTP Authorization header should be set

Security Scheme Type HTTP
HTTP Authorization Scheme basic

apiKeyAuth

In each API call an API key must be provided, this will be used by the storebox.com system to authenticate the calling system and authorize it to perform the requested operation.

The key is a shared secret value created by Storebox and delivered to you upon registration.

The key can be changed at regular intervals.

Security Scheme Type API Key
Header parameter name: Authorization

Receipts

Receipt operations

Create new receipt

Create a new receipt.

In the production environment, none of the receipt parameters are validated on upload. This means that a receipt may be accepted even though it is not valid. In test, basic receipt validation is done and invalid receipts will be rejected with HTTP status code 400.

Authorizations:
Request Body schema: application/json
userId
required
Array of objects
receiptId
object

Optional external receipt id

merchantId
required
string

Identifier of the merchant – value assigned by Storebox

store
required
object
orderDate
required
string <date-time>

Date and time of order including timezone information as defined by ISO8601. It is mandatory to include the offset from UTC time respecting daylight saving.

orderNumber
required
string <= 64 characters

Unique number for the receipt

salesEmployeeName
string

Name of the cashier

headerText
Array of strings

Header lines which can have random data. Will be displayed in the top of the receipt.

footerText
Array of strings

Footer lines which can have random data. Will be displayed in the bottom of the receipt.

terminalId
string <= 32 characters

Number identifying the terminal attached to the point of sale

sequenceNumber
string <= 32 characters

The receipt sequence number. This may be unique in itself or as a combination of storeId, terminalId and sequence number

receiptImage
object
barcode
object
orderLines
required
Array of objects
totalOrderPrice
required
object
payments
required
Array of objects

List of payment methods used in the purchase

Responses

201

The receipt was accepted. This does not mean that the receipt will be processed, only that it was sent to the internal processing queues. The receipt id is available in the Location header.

400

Invalid receipt data. Note that this will only be returned on the test environment.

post /api/receipt-receiver/v2/receipts

Production

https://api.storebox.com/api/receipt-receiver/v2/receipts

Test

https://test-api.storebox.com/api/receipt-receiver/v2/receipts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId":
    [
    ],
  • "receiptId":
    {
    },
  • "merchantId": "storebox",
  • "store":
    {
    },
  • "orderDate": "2021-10-25T09:57:35Z",
  • "orderNumber": "12345678",
  • "salesEmployeeName": "John Doe",
  • "headerText":
    [
    ],
  • "footerText":
    [
    ],
  • "terminalId": "17193CT26617792",
  • "sequenceNumber": "10",
  • "receiptImage":
    {
    },
  • "barcode":
    {
    },
  • "orderLines":
    [
    ],
  • "totalOrderPrice":
    {
    },
  • "payments":
    [
    ]
}

Update existing receipt

If a receipt with receiptId already exists, that receipt will be overwritten otherwise it will be stored as a new receipt.

Authorizations:
path Parameters
receiptId
required
string

Issued by Create receipt in the Location header.

Request Body schema: application/json
userId
required
Array of objects
receiptId
object

Optional external receipt id

merchantId
required
string

Identifier of the merchant – value assigned by Storebox

store
required
object
orderDate
required
string <date-time>

Date and time of order including timezone information as defined by ISO8601. It is mandatory to include the offset from UTC time respecting daylight saving.

orderNumber
required
string <= 64 characters

Unique number for the receipt

salesEmployeeName
string

Name of the cashier

headerText
Array of strings

Header lines which can have random data. Will be displayed in the top of the receipt.

footerText
Array of strings

Footer lines which can have random data. Will be displayed in the bottom of the receipt.

terminalId
string <= 32 characters

Number identifying the terminal attached to the point of sale

sequenceNumber
string <= 32 characters

The receipt sequence number. This may be unique in itself or as a combination of storeId, terminalId and sequence number

receiptImage
object
barcode
object
orderLines
required
Array of objects
totalOrderPrice
required
object
payments
required
Array of objects

List of payment methods used in the purchase

Responses

200

The receipt was accepted. This does not mean that the receipt will be processed, only that it was sent to the internal processing queues.

400

Invalid receipt data. Note that this will only be returned on the test environment.

put /api/receipt-receiver/v2/receipts/{receiptId}

Production

https://api.storebox.com/api/receipt-receiver/v2/receipts/{receiptId}

Test

https://test-api.storebox.com/api/receipt-receiver/v2/receipts/{receiptId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId":
    [
    ],
  • "receiptId":
    {
    },
  • "merchantId": "storebox",
  • "store":
    {
    },
  • "orderDate": "2021-10-25T09:57:35Z",
  • "orderNumber": "12345678",
  • "salesEmployeeName": "John Doe",
  • "headerText":
    [
    ],
  • "footerText":
    [
    ],
  • "terminalId": "17193CT26617792",
  • "sequenceNumber": "10",
  • "receiptImage":
    {
    },
  • "barcode":
    {
    },
  • "orderLines":
    [
    ],
  • "totalOrderPrice":
    {
    },
  • "payments":
    [
    ]
}

Documents

Documents provides merchants the ability to upload and attach documents, i.e. user guides, Quick start tutorials, warrenty documents and many more, to receipts.

Upload a document to a receipt

Upload a document to a receipt. The upload is executed as a multipart/form-data request.

Authorizations:
Request Body schema: multipart/form-data
metadata
object
document
string <binary>

Responses

202

Document succesfully attached to receipt

410

Receipt not available (no retry)

412

Receipt currently not available (retry at most 3 times)

post /api/v1/documents

Production

https://api.storebox.com/api/v1/documents

Test

https://test-api.storebox.com/api/v1/documents

Users

The user operations in the POS API serve two purposes

  • Check if an user is Storebox user
  • Check if an user has indicated that they do not want printed receipts (green profile)

The ECR can use the appropriate endpoint to check the identity token and make the choice of what to do.

It is optional to do a lookup of Storebox users before sending the receipts. The Storebox system will discard the receipts that are not matched. It is the preferred method to send all the receipts.

A Storebox user can configure in the Storebox app/website that they prefer not a get a printed receipt.

This is configuration returned in success user lookups

{
    "prefersNonPrintedReceipts": true
}

When a card token is used as user lookup, multiple users may have that card added to their profile. In this case prefersNonPrintedReceipts will return false if any of the users have disabled green profile

lookupUserByCardToken

Lookup user by a card token from the terminal.

Authorizations:
path Parameters
token
required
string

The card token from the terminal

Responses

200

Storebox user was found

404

No Storebox user found

get /api/receipt-receiver/v2/users/tokens/{token}

Production

https://api.storebox.com/api/receipt-receiver/v2/users/tokens/{token}

Test

https://test-api.storebox.com/api/receipt-receiver/v2/users/tokens/{token}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "prefersNoPrintedReceipts": true
}

lookupUserByEmail

Lookup user by a email. Only verified email will be searched.

Authorizations:
path Parameters
email
required
string <email>

The email registered in Storebox

Responses

200

Storebox user was found

404

No Storebox user found

get /api/receipt-receiver/v2/users/emails/{email}

Production

https://api.storebox.com/api/receipt-receiver/v2/users/emails/{email}

Test

https://test-api.storebox.com/api/receipt-receiver/v2/users/emails/{email}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "prefersNoPrintedReceipts": true
}

lookupUserByEmailHash

Lookup user by a email hash. Only verified email will be searched. The hash is created by sha(email+salt). The salt value is delivered by Storebox upon request.

Authorizations:
path Parameters
emailHash
required
string <email>

The sha256 hash of the email registered in Storebox

Responses

200

Storebox user was found

404

No Storebox user found

get