Receipt Data API (v1)

Download OpenAPI specification:Download

The Storebox Receipt Data API is the programming interface for retrieval of receipt data from Storebox.

Storebox Receipt Data API provides trusted 3rd parties like payment service providers the opportunity to enrich their end users’ experience with detailed information of not only the payment data, but also the enriched transaction data regarding their actual purchases.

The intended audience for this documentation is technicians developing system integration to Storebox. The Storebox Receipt Data API is organized around REST. The API is designed to have predictable, resource oriented URLs and to use more responsive codes to indicate API errors. The interface use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON is the data interchange format and will be returned from the API, including errors.

Caching

This API must be as consistent as possible and generally calls are always passed on the the backend server to processed and no cache is used.

However merchant logos are a mostly static resource and of a moderate size and must therefore be cached on the partner server and/or mobile device. When logo.version field change, it signals that a new version should be fetched from Storebox servers.

When the inbox is requested or a search is performed, for most users the full dataset is returned and no paging is used. This is signalled by absence of both previous and next pointers. When the full dataset is returned then the app must sort the list on the device if the user wishes to change sort order. This will give a more responsive app and take some strain from the Storebox backend servers.

Return codes

All the REST API calls returns a http status code, this defines the status of the call, and should be checked by the caller. The first digit of the code indicates the class of error and how to handle the response.

CodeNameDescriptionAction
200OKRequest received, validated, accepted and processedNo action
201Bad requestResource received and createdNo action
400Request not accepted. Error in format of requestInspect formatting and credentials. Do not resend request
401UnauthorizedThe username and/or password is invalidInspect formatting and credentials. Do not resend request
403ForbiddenInvalid security tokenInspect formatting and credentials. Do not resend request
500Internal Server ErrorUnknown error on the service serverAlternative resend request after some time

Authentication

apiKeyAuth

All API calls must be made using SSL as transport level security. HTTPS on port 443 must be the protocol to use.

Each api user is given a apiKey that must be placed in the Authorization header to access the endpoints. The format of the Authorization header is

Authorization: {apiKey}

If the API user wants higher security then incoming connections can be protected by a client certificate in addition to HTTPS on the server.

For enhanced security a security token can be generated for each request and response. The signature is calculated in a way that must be agreed upon between partner and Storebox. If a signature is used then the Authorization header will have this format.

Request

Authorization: {apiKey}:{signature}

Response

Authorization: {signature}
Security Scheme Type API Key
Header parameter name: Authorization

Receipts

Receipt operations

Get receipts

Return all the receipts for a user

Authorizations:
path Parameters
userId
required
string

The user id that was returned on creation/linking or on OTP validation

query Parameters
orderBy
required
string

Field to order by. Allowed values are store, date and total

direction
required
string

The sort order. Allowed values are asc and desc

folderId
string

The folder to list. Default value is inbox

search
string

Freetext search term. Will search receipt lines and merchant names.

offset
number

Start at the result index

limit
number

The number of results to fetch. Default is 50.

merchantId
string

Only fetch receipts from this merchant. The value is the Storebox defined merchant id.

startDate
string

Date search range start in ISO-8601 format. Example 2015-06-29T15:50:12+02:00.

endDate
string

Date search range end in ISO-8601 format.

startGrandTotal
number

Grandtotal search range start. Example 150.50.

endGrandTotal
number

Grandtotal search range end.

Responses

200

Successfully fetched the receipts

get /receipt-data/v1/users/{userId}/receipts

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "totalSize": 42,
  • "receipts":
    [
    ]
}

Get receipt details

Return the receipt details

Authorizations:
path Parameters
userId
required
string

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string

The id of the receipt

Responses

200

Successfully fetched the receipt details

404

Receipt not found

get /receipt-data/v1/users/{userId}/receipts/{receiptId}

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}

Response samples

Content type
Copy
Expand all Collapse all
{
  • "receiptId": "4sh8tz51gwthdbdywap34zpmwim7e9z7",
  • "merchantId": "storebox",
  • "purchaseDateTime": "2018-11-01T10:34:23+02:00",
  • "grandTotal":
    {
    },
  • "vatRates":
    [
    ],
  • "merchant":
    {
    },
  • "receiptLines":
    [
    ],
  • "payments":
    [
    ],
  • "barcode":
    {
    },
  • "receiptCopyHistory":
    [
    ],
  • "optionals":
    {
    },
  • "matchedCards":
    [
    ]
}

Delete receipt

Delete a receipt

Authorizations:
path Parameters
userId
required
string

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string

The id of the receipt

Responses

200

Successful delete

404

Receipt not found

delete /receipt-data/v1/users/{userId}/receipts/{receiptId}

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}

Copy receipt

Copy a receipt to another folder and possible another user

Authorizations:
path Parameters
userId
required
string

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string

The id of the receipt

Request Body schema: application/json
toUserId
required
string

The user to copy the receipt to. If no user is specified the current user is assumed

toFolderId
required
string

The folder to copy the receipt to

Responses

200

Successful copy

404

Receipt, user or folder not found

post /receipt-data/v1/users/{userId}/receipts/{receiptId}/copy

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/copy

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/copy

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "toUserId": "b2rddutf7sktwdr0qi8y51hz4ewosvha",
  • "toFolderId": "inbox"
}

View receipt by external receipt id

API endpoints that return data in HTML for presentation in a webview or iframe. They all require authentication, so the endpoints needs to be proxied by the callers middleware.

Return the rendered representation of a receipt based on an external id. See the POS API for external ids.

Security

This endpoint is accessed without specifying the user. It is therefore required by the caller to verify that the enduser has the correct access rights to see the receipt.

To avoid parameter tampering (i.e. the enduser changing the receipt id parameter) an extra security measure is added to this endpoint which requires a signature of the parameters using HMAC-SHA256. The shared secret is the API key and the signing data is the parameters separated by colon.

The HMAC value should then be Base64 encoded and set in the HTTP header X-Auth-signature.

Authorizations:
path Parameters
receiptId
required
string

The external id of the receipt (i.e. not the Storebox receipt id)

query Parameters
type
required
string

The external receipt id type. This has to be the same as the only used when sending the receipt to the POS API.

header Parameters
X-Auth-signature
required
string

Base64 encoded HMAC parameter signature

Responses

200

The receipt HTML content

get /receipt-data/v1/receipts/{receiptId}

Production

https://rda.storebox.com/receipt-data/v1/receipts/{receiptId}

Test

https://test-rda.storebox.com/receipt-data/v1/receipts/{receiptId}

PDF

PDF operations

Get PDF

Get PDF version of receipt. It depends on the API user configuration if the merchant version or Storebox version is returned.

Authorizations:
path Parameters
userId
required
string
Example: u2dxq5u5lpsyd33513srwp0gkggn0ml7

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string
Example: vk03261wef66qa8mkqiuez7sf1i8yywv

The id of the card either from creation callback or from list cards

query Parameters
lang
string

The language of static text in the PDF. For example da, no, sv, fi or en.

Responses

200

PDF returned

get /receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf

Get PDF session

Get a session id where the PDF can be accessed without API key for 15 min.

Authorizations:
path Parameters
userId
required
string
Example: u2dxq5u5lpsyd33513srwp0gkggn0ml7

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string
Example: b2rddutf7sktwdr0qi8y51hz4ewosvha

The id of the card either from creation callback or from list cards

Responses

200

PDF session id returned

get /receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf-session

Production

https://rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf-session

Test

https://test-rda.storebox.com/receipt-data/v1/users/{userId}/receipts/{receiptId}/pdf-session

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "sessionId": "5yuns6oeqoo3nzhbqhw4ya4s50njzh5j"
}

Get PDF

Get PDF from a session id

path Parameters
userId
required
string
Example: 882x6mid0he8pgozj0xt5yxm0yol8kg3

The user id that was returned on creation/linking or on OTP validation

receiptId
required
string
Example: 76puixjb221vjhbu4q3a81gaaieca0iz

The id of the card either from creation callback or from list cards

sessionId
required
string
Example: 4sh8tz51gwthdbdywap34zpmwim7e9z7

Session id that is authorized for access

query Parameters
lang
string

The language of static text in the PDF for example da, no or sv.

Responses

200

PDF session id returned

get /receipt-data/v1/pdf-sessions/{sessionId}

Production

https://rda.storebox.com/receipt-data/v1/pdf-sessions/{sessionId}

Test

https://test-rda.storebox.com/receipt-data/v1/pdf-sessions/{sessionId}

Cards

card operations

Add card

For online card registration via web or a smartphone app, a Storebox provided PCI-DSS compliant webpage must be used to comply with international card issuer standards. This webpage can be integrated with an existing webpage using an iframe or a mobile app by using a webview.

The flow can be seen in the following Figure:

Upon completed card registration Storebox can send a notification. See section Card Created Notification

When registering a new card the id must be known in the system or a 404 error is returned.

CSS and HTML Structure

The card input frame is styled by the caller via the CSS specified by cssurl in the initial call. The following structure is used.

<form class="">
  <div class="field field-input">
    <div class="field-label">Kortnummer</div>
    <input type="tel" value="" placeholder="Kortnummer" name="CardNumber" id="CardNumber" autocomplete="off" required="" class="">
    <span class="field-validation-error">Ugyldigt kortnummer</span>
  </div>
  <div class="field field-input">
    <div class="field-label">Udløbsmåned</div>
    <input type="tel" value="" placeholder="Indtast udløbsmåned" name="ExpMonth" id="ExpMonth" autocomplete="off" required="" maxlength="2" class="">
    <span class="field-validation-valid"></span>
  </div>
  <div class="field field-input">
    <div class="field-label">Udløbsår</div>
    <input type="tel" value="" placeholder="Indtast udløbsår" name="ExpYear" id="ExpYear" autocomplete="off" required="" maxlength="2" class="">
    <span class="field-validation-valid"></span>
  </div>
  <div class="field field-btn">
    <input type="submit" value="Gem kort" class="button" id="submit" name="add" disabled="disabled">
  </div>
</form>

JSON language file

A JSON file specified by languageurl configures the text displayed in the card input. The file contains a translation label and value like in the following example. The file must be UTF-8 encoded.

{
  "expMonth": {
    "errorInvalid": "Skal være mellem 1 og 12",
    "label": "Udløbsmåned",
    "placeholder": "Indtast udløbsmåned"
  },
  "expYear":{
    "label": "Udløbsår",
    "placeholder": "Indtast udløbsår",
    "errorExpired":"Kortet er udløbet"
  },
  "error":{
    "generalError":"Der skete en fejl. Prøv venligst igen",
    "maxCards":"Du kan ikke tilføje flere kort" },
  "btn":{
    "save":"Gem kort"
  },
  "card":{
    "errorInvalid":"Ugyldigt kortnummer",
    "unsupportedType":"Denne korttype kan ikke bruges",
    "label":"Kortnummer",
    "placeholder":"Indtast kortnummer",
    "duplicate":"Kortet er allerede registreret"
  }
}

The text values are cached and are only downloaded if the URL changes. For this reason a version parameter should be used in the languageurl, for example http://.../en.json?v=1. Refrain from using a constantly changing parameter, like a timestamp.

Card Created Notification

When a new card has been fully processed a notification can be sent. In order to send a notification Storebox must know the endpoint URL and authentication header(s).

A call to list card is only guaranteed to include a newly created card after the notification has been sent. Under some circumstances a notification may be sent more than once.

The notification will be sent as a POST request.

Storebox does not handle the response sent from this endpoint.

Notification format

{
  "id": "123456",
  "cardId":ft8e74brrvhee38zw9vu32urgbjaswg6,
  "cardtype": 1,
  "cardno": "457100XXXXXX0000",
  "expmonth": 12,
  "expyear":21
}

Notification fields

NameTypeDescription
idstringId of the user the card was appended to
cardIdstringId of the card
cardtypenumbertype of the added card
cardnostringMasked card number
expmonthnumberExpiry month of the card
expyearnumberExpiry year of the card
query Parameters
id
required
string

Id of the user that should have the card appended. Note This id is used to lookup the user, and the user will get the card appended

provider
required
string

Identity of the caller. Issued by Storebox. Since the card input runs directly in the endusers browsers, api-key authentication is not used. The provider value is used to ensure caller identity along with the hash parameter

accepturl
required
string

The URL where the page is redirected after successful card submit. Note The card may not have finished processing yet

cssurl
required
string

Absolute URL for the CSS file for input styling.