Storebox
API docs by Redocly

Vault API (v1)

Download OpenAPI specification:Download

Storebox: support@storebox.com URL: http://developer.storebox.com Terms of Service

This document contains a technical description for adding cards to Storebox PCI DSS Certified environment.

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

The API is organized around REST. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON is the data interchange format and will be returned in responses from the API, including errors.

PCI DSS scope

Everything that interacts with a card number (even if it is encrypted) is in PCI-scope and thereby is required to be PCI DSS certified. A personal device (for example a phone) is regarded as an insecure and hostile environment where the PCI requirement does not apply.

This means that a mobile app is allowed to process card numbers, but the app is only allowed to send the card number directly to a PCI DSS environment.

The card number may never leave the device unless it is sent to a PCI DSS certified environment, i.e. no proxy or middleware inbetween!

App vs Server authentication

The API is meant to be used either from a client app or server. Since the app environment is hostile and card data is not allowed to pass-through a non-PCI backend, the API has special methods to handle this type of use-case.

App authentication

The app client authentication is done in the following steps

  • The app establishes a safe connection with its backend (using login or similar)
  • The backend requests a client token from Vault API using HTTP Basic authentication
  • The backend returns the client token to the app
  • The app encrypts the card and requests Vault API using the client token as a bearer token

Server

If cards are added from a server, HTTP Basic is the prefered method of authentication.

The server is required to be in a PCI DSS certified environment.

Rate limiting

If the API is intented to be used in bulk, for example adding multiple cards within a short timetrame, the originating IP addresses may end up being blacklisted. For this use-case please supply Storebox with the addresses in advance and they will be whitelisted.

Strong Customer Authentication

To have Strong Customer Authentication (SCA) like 3D Secure activated, please contact Storebox partner support.

The SCA flow is web based and must therefore be completed in a web context like a browser or a webview. Upon adding a card also a scaAcceptURL and scaDelineURL must be provided and if SCA is activated an enrollmentUrl will be returned to start the flow.

The flow is completed successfully if the scaAcceptURL is called and the card is then added to Storebox. If the scaDeclineURL is called then the SCA was unsuccesfull and the card was not added to Storebox.

Client Authentication

Authentication operations.

Get client token

Get an authentication token to use with Add Card and that is safe to use in an insecure environment.

Note that this endpoint should never be used from an insecure environment, only from a backend server.

Authorizations:
basicAuth
query Parameters
platform
required
string
Enum: "storebox" "loyalty" "rda" "cardapi"

Add the card to this platform

provider
string

Provider name (Issued by Storebox). This is required is the platform is loyalty.

Responses

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1FiJ9.eyJzdWIiOiJkYWdyb2ZhX3Rlc3QlLCJleHAiOjE1ODAyMTcgMTIsInBsYXRmb3JtIjoibG95YWx0eSJ9.9DbjnUPvztqfQmbnVbHvDFUuWCHZHjaWhk1MtRBGDog"
}

Cards

Card operations.

Add card

Add card from an external environment. When cards are added through our API it is required that the external environment is PCI-DSS certified. The API accepts an encrypted package containing the full cardnumber and expiry month/year.

The encrypted payload is a JSON string in the form:

{
  "expiry": {
    "year": 25,
    "month": 1
  },
  "cardNumber": "...",
  "cardNumberType": "funding"
}

cardNumberType is optional and will default to funding. The possible values are

  • funding - The value of cardNumber is interpreted as a normal funding PAN
  • par - PAR value of a card. Note that PAR values added this way will only affect PAR-based payment methods
  • bankaxept - The value of cardNumber is interpreted as an account number
  • token - The value of cardNumber is interpreted as Token PAN for example card numbers issues for xPay wallets

expiry is required for funding but is otherwise optional.

The string is encrypted and Base64 encoded. The supported encryption algorithm is RSA with OAEP padding.

Test example of generating the card payload from the command line.

cat <carddata.json> | openssl pkeyutl  -encrypt -pubin -inkey <transport.pem> -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256 | base64

The resulting card payload should be added in the data request property.

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
data
required
string <= 4096 characters

Encrypted card data Base64 encoded.

userId
required
string <= 64 characters ^[a-zA-Z0-9\-_]{4,64}$

External user id

callbackURL
string <= 1024 characters

Optional URL that is requested when the card is added. Only HTTPS is supported

scaAcceptURL
string <= 1024 characters

URL required if card needs Strong Customer Authentication (SCA). Will be requested when SCA flow is completed successfully.

scaDeclineURL
string <= 1024 characters

URL required if card needs Strong Customer Authentication (SCA). Will be requested when SCA flow is completed unsuccessfully.

Responses

Request samples

Content type
application/json
{
  • "data": "UmATO80JIhQSqgJY/jjy1xGrX52wDYVFpmxr0L/biAhIQ0s5Q6xtsdh+k/7NW3JxY1vmyPdDzqO4o1w7zVrpbg3NW7m2drG0K13JgZ+8sMJT3w7wivBoK+cHig994Z/d1F6OFkLpvx/DJBBDDn0NBC6xeF/eaA8I/kN6PXSWN6EJvRRvltbYIjflHo3qxIOxdDJpq0bG0aEii7c9ysyC//UTfGplA1tADRg1Df4cZjhFHX/7exlbiJMLbrLUpLtmgOiK8fyaZdw7I1tt3P6OF60hSxeOnaI4FYxM2BvYQlyhP/VmEaKibhf6RMWEmrgZPtvMaQT730zQrPJoXCQpNA==",
  • "userId": "9o79ggcu2j28uszftsnwy9t9r0bjl23v",
  • "callbackURL": "https://...",
  • "scaAcceptURL": "https://.../sca-accept",
  • "scaDeclineURL": "https://.../sca-decline"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "reason": "OK",
  • "externalCardId": "9o79ggcu2j28uszftsnwy9t9r0bjl23v",
  • "enrollmentUrl": "https://..."
}

Update card

Update an existing card with additional card data, like PAR or Token PANs.

The request content is the same as Add Card and the documentation can be found here.

The normal use-case is to add PAR to an existing card. This is done by sending the following JSON as the encrypted payload in the data property.

{
  "cardNumber": "<par-value>",
  "cardNumberType": "par"
}

Note that cardNumberType=funding is not allowed. In this case a new card has to be added instead.

Authorizations:
bearerAuthbasicAuth
path Parameters
externalCardId
required
string

Card id that was returned during card creation

Request Body schema: application/json
data
required
string <= 4096 characters

Encrypted card data Base64 encoded.

callbackURL
string <= 1024 characters

Optional URL that is requested when the card is added. Only HTTPS is supported

Responses

Request samples

Content type
application/json
{
  • "data": "UmATO80JIhQSqgJY/jjy1xGrX52wDYVFpmxr0L/biAhIQ0s5Q6xtsdh+k/7NW3JxY1vmyPdDzqO4o1w7zVrpbg3NW7m2drG0K13JgZ+8sMJT3w7wivBoK+cHig994Z/d1F6OFkLpvx/DJBBDDn0NBC6xeF/eaA8I/kN6PXSWN6EJvRRvltbYIjflHo3qxIOxdDJpq0bG0aEii7c9ysyC//UTfGplA1tADRg1Df4cZjhFHX/7exlbiJMLbrLUpLtmgOiK8fyaZdw7I1tt3P6OF60hSxeOnaI4FYxM2BvYQlyhP/VmEaKibhf6RMWEmrgZPtvMaQT730zQrPJoXCQpNA==",
  • "callbackURL": "https://..."
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "reason": "OK"
}