User API (v1)

Download OpenAPI specification:Download

The Storebox User API is a simple API to maintain attributes on a user.

The API also allows signup of users directly from the ECR.

Example flow

Figure 1 shows an overall sequence flow showing integration points for a signup directly from the ECR. The enduser must click the link and verify the phone number before a receipt can be matched.

Authentication

basicAuth

The simplest authentication scheme is to use HTTP Basic authentication.

In each API call the username/password 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 username and password will be delivered by Storebox upon registration. The password can be changed at regular intervals. For each API call HTTP Authorization header should be set:

Authorization: Basic {Base64(<username>:<password>)}
Security Scheme Type HTTP
HTTP Authorization Scheme basic

apiKeyAuth

If the API is used in a hostile environment, for example an app, HTTP Basic authentication should not be used. Instead the API allows a bearer token authentication using JWT tokens.

To avoid the transmitting the key over the wire the API key is wrapped in a JWT token, containing the URL, HTTP method and expiry as the claim. The same username/password is used as with HTTP Basic authentication however the username is set as issuer (iss) and the password is used as JWT token secret.

{
    "iss": "<username>",
    "sub": "/api/v1/<endpoint>",
    "method": "POST",
    "exp": 1532329721
}

The subject (sub) has to be set to the endpoint that the client is trying to access, method to the HTTP method and expiration time (exp) to the date when the token should expiry as a NumbericDate (i.e. seconds from Epoch)

The token is added to every request in the Authorization HTTP header.

Authorization: Bearer <jwt-token>

For an introduction to JWT please visit jwt.io.

Security Scheme Type API Key
Header parameter name: Authorization

Signup

Two different signup flows are supported:

  1. Storebox controlled term accept
  2. Customer controlled term accept

In Storebox controlled term accept, the link sent in the verification SMS sends the enduser to a generic term accept page controlled by Storebox. This page contains an IFrame and an "Accept" button. The IFrame will load an external webpage, which must be provided, containing the terms of the loyalty program. Upon Accept, the enduser will be redirected to the landingpage:

In Customer controlled term accept, the verification SMS link sends the enduser directly to an external signup page. The link contains a linkCode. When the enduser has entered all mandatory profile information and accepted the terms, the signup service can call Storebox with the linkCode. Storebox will then create the user.

Call linkcode exists endpoint to ensure the linkCode exists before the user starts to enter signup information.

When users have accepted the terms call linkcode verify to create the user

New user/Add card

Creates a new user with the given phone number. If the phone number is already known the card is added to the existing user. If the phone number is not known a sms with a validation link is sent.

Authorizations:
Request Body schema: application/json
phonenumber
required
string

Phone number in MSISDN format

truncatedPan
required
string

Masked payment card number

token
required
string

Card token from the terminal

payment
boolean

Indicate if the card should be added to recurring payments

memberId
string

Set the member id instead of having the system generate one

Responses

200

Card added to existing user

202

Verification sms sent

409

Card already registered (on any user)

412

Max card reached

post /api/v1/signup

Production

https://user.storebox.com/api/v1/signup

Test

https://test-user.storebox.com/api/v1/signup

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phonenumber": "4511111111",
  • "truncatedPan": "457100XXXXXX0001",
  • "token": "2797aa22047e89e0b39c1626b1be53cf246051b4927f2be7108bf5476edf4937",
  • "payment": true,
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f"
}

New user/Add Token

In cases where the card is not known at signup time, the enduser can be created based on the card token received from the card terminal. This endpoint creates a new user with the given phone number. If the phone number is already known the token is added to the existing user. If the phone number is not known a sms with a validation link is sent.

Authorizations:
Request Body schema: application/json
phonenumber
required
string

Phone number in MSISDN format

token
required
string

The cardtoken that the enduser should be identified on as received from the card terminal.

tokenType
required
string

The type of the token. This value is specified by Storebox during setup

truncatedPan
string

Send the truncatedPan if possible. This will be returned when getting a users cards. If not set token will be returned when getting a users cards.

Responses

200

Token added to existing user

202

Verification sms sent

409

Token already registered (on any user)

412

Max card reached

post /api/v1/tokensignup

Production

https://user.storebox.com/api/v1/tokensignup

Test

https://test-user.storebox.com/api/v1/tokensignup

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phonenumber": "4511111111",
  • "token": "2797aa22047e89e0b39c1626b1be53cf246051b4927f2be7108bf5476edf4937",
  • "tokenType": "viking_nordic",
  • "truncatedPan": "457100XXXXXX0000"
}

New user without card

Signup to the service without card information. This endpoint sends an OTP via sms to the phone number given.

Authorizations:
path Parameters
phonenumber
required
string

Phone number in MSISDN format

Request Body schema: application/json
memberId
string

Enables the client to specify a member identifier. If omitted the system will generate one automatically.

smsType
integer
Default: 1

Allow the client to specify the flow of the signup.

  • 1: Will send an OTP SMS which must be validated through endpoint Validate OTP
  • 2: Will send a verification SMS containing a signup link. User is created when link is clicked and a redirect sends the user to the landingpage.

Responses

200

Success

409

Phone number is already in use

post /api/v1/signup/{phonenumber}

Production

https://user.storebox.com/api/v1/signup/{phonenumber}

Test

https://test-user.storebox.com/api/v1/signup/{phonenumber}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",
  • "smsType": 1
}

Link code exists

Check if a link code exists in Storebox' system, before the user enters signup information.

Authorizations:
path Parameters
linkCode
required
string
Example: p7hy9

The linkCode created by Storebox during verification preparation

Responses

200

linkCode exists and ready to be verified

404

linkCode not found. Link codes are cleaned after 30 days, or the user may already have used the it

get /api/v1/linkcodes/{linkCode}/exists

Production

https://user.storebox.com/api/v1/linkcodes/{linkCode}/exists

Test

https://test-user.storebox.com/api/v1/linkcodes/{linkCode}/exists

Verify link code

Create the user referenced by the linkCode. It is the responsebility of the caller to ensure the enduser has accepted terms before this endpoint is called.
To avoid situations where Storebox responds with an unknown linkCode error, please see Link code exists endpoint.

Authorizations:
path Parameters
linkCode
required
string
Example: p7hy9

The linkCode created by Storebox during verification preparation

Request Body schema: application/json
memberId
string [ 4 .. 32 ] characters

The external member id of the user. If omitted a member id will be created

Responses

200

Request processed - see response for success state

post /api/v1/linkcodes/{linkCode}/verify

Production

https://user.storebox.com/api/v1/linkcodes/{linkCode}/verify

Test

https://test-user.storebox.com/api/v1/linkcodes/{linkCode}/verify

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberId": "6fpw801mmb081vrn3jvqnr293v66c2ix"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "state": 0
}

Users

User CRUD operations. If used from a hostile environment using bearer token authentication the header X-Storebox-user-token is required with the token from the authentication process (See User Authentication).

Get user

Returns the user and added user parameters.

Authorizations:
path Parameters
userId
required
string
Example: 0467q4wqp7hyyxei3amxauz808vudi5x

The user id from the OTP process

Responses

200

User found

404

User not found

get /api/v1/users/{userId}

Production

https://user.storebox.com/api/v1/users/{userId}

Test

https://test-user.storebox.com/api/v1/users/{userId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phoneNumber": "4511111111",
  • "userId": "string",
  • "parms":
    [
    ]
}

Update user

Arbitrary information can be stored on a user in a key/value pair form. There is no validation of the parameters. If phone number is present an OTP is sent to it. The phone number will not be assigned to the user before the OTP is validated.

Authorizations:
path Parameters
userId
required
string
Example: 0467q4wqp7hyyxei3amxauz808vudi5x

The user id from the OTP process

Request Body schema: application/json
phonenumber
string

Users phone number in MSISDN format

parms
Array of objects

Key-value pairs stored on the user. This could be something like age, gender or any value

Responses

200

User updated successfully

404

User not found

409

Phonenumber already used

put /api/v1/users/{userId}

Production

https://user.storebox.com/api/v1/users/{userId}

Test

https://test-user.storebox.com/api/v1/users/{userId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phonenumber": "string",
  • "parms":
    [
    ]
}

Delete user

Delete the user with the supplied id.

Authorizations:
path Parameters
userId
required
string
Example: 0467q4wqp7hyyxei3amxauz808vudi5x

The user id from the OTP process

Responses

200

User deleted successfully

404

User not found

delete /api/v1/users/{userId}

Production

https://user.storebox.com/api/v1/users/{userId}

Test

https://test-user.storebox.com/api/v1/users/{userId}

Get user token

If users do not have their payment cards, this endpoint can be used to retrieve a token on the user. A token can only be returned if the user previously has registered a card.

path Parameters
phonenumber
required
string

Phone number in MSISDN format

Responses

200

User token found

get /api/v1/users/{phonenumber}/token

Production

https://user.storebox.com/api/v1/users/{phonenumber}/token

Test

https://test-user.storebox.com/api/v1/users/{phonenumber}/token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "3f8eef9a2833db7dad5393210aef92ecb876e85fa03356b5b974e1bbf9cfbd61"
}

Get user member id

Get the associated member id with a phone number

path Parameters
phonenumber
required
string

Phone number in MSISDN format

Responses

200

User token found

404

User not found

get /api/v1/users/{phonenumber}/loyaltyMemberId

Production

https://user.storebox.com/api/v1/users/{phonenumber}/loyaltyMemberId

Test

https://test-user.storebox.com/api/v1/users/{phonenumber}/loyaltyMemberId

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId": "xy2vk5trm9ctino4ddy2xhey7m7japgg"
}

OTP

OTP validation

Send OTP

Send a one-time-password to the specified phone number.

path Parameters
phonenumber
required
string

Phone number in MSISDN format

Responses

200

OTP successfully sent to the SMS gateway. This does not mean that it is actually delivered to the end-user phone.

404

Phone number not found

put /api/v1/users/otp/{phonenumber}

Production

https://user.storebox.com/api/v1/users/otp/{phonenumber}

Test

https://test-user.storebox.com/api/v1/users/otp/{phonenumber}

Validate OTP

Validates the match between the otp and the phonenumber. The otp is deleted and cannot be used again.

path Parameters
phonenumber
required
string

Phone number in MSISDN format

otp
required
string

The OTP to validate

Responses

200

OTP accepted for already existing user

201

OTP accepted and new user has been created

404

No user found with otp and phone number

put /api/v1/users/otp/{phonenumber}/code/{otp}

Production

https://user.storebox.com/api/v1/users/otp/{phonenumber}/code/{otp}

Test

https://test-user.storebox.com/api/v1/users/otp/{phonenumber}/code/{otp}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId": "xy2vk5trm9ctino4ddy2xhey7m7japgg"
}

User authentication

If the API is used as client-to-server API, the user operation requires an authentication token. This token has to be present as a header X-Storebox-user-token, when requesting user operations (/users)

Request access token using OTP

Request Body schema: application/json
phonenumber
string

Phone number in MSISDN format

Responses

200

OTP successfully sent to the SMS gateway. This does not mean that it is actually delivered to the end-user phone.

404

Phone number not found

post /api/v1/auth/otp

Production

https://user.storebox.com/api/v1/auth/otp

Test

https://test-user.storebox.com/api/v1/auth/otp

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phonenumber": "4511111111"
}

Verify OTP request

Verify the token request using OTP. When succesful verified an access token will be returned that has to be used in the user endpoints.

Request Body schema: application/json
phonenumber
string

Phone number in MSISDN format

otp
string

The OTP

Responses

200

OTP accepted for existing user

201

OTP accepted and user has been created

404

No user found with otp and phone number

put /api/v1/auth/otp

Production

https://user.storebox.com/api/v1/auth/otp

Test

https://test-user.storebox.com/api/v1/auth/otp

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "phonenumber": "4511111111",
  • "otp": "1234"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ7XCJ1c2VySWRcIjpcImFyMHJ1c2w2cWYxNXAxNWc2MHQzaDI5cmNyNnJlZDdxXCIsXCJtc2lzZG5cIjpcIjQ1Mjc1NzU3MjdcIn0iLCJleHAiOjE1MzQ1MTQwMzR9.RiQxPZ8YLcmw38Pa1mjBvaegMHhk48FO9pQNJRab_o"
}

Landing page

The landing page is a HTML page hosted externally for acquiring user consent.

The landing page is requested with a linkCode parameter ex.:

https://domain.tld/landingpage?linkCode={value}

This linkCode is used to finalize the creation process after consent has been given.

A description of the flow can be found in Customer controlled term accept under Signup.

For security reasons the linkCode is deleted after the request has been completed and cannot be used to update user information again.

Notifications

When certain events happen within the user platform, a notification can be dispatched.

In order to setup notications, Storebox must receive an URL per notification type with static authentication headers. Storebox will not append information of the event type to the URL.

Storebox monitors the response code returned, but will not handle the response body.

Note: None of the endpoints, in the "Notifications" section, exists in the user API, but are endpoints the integrator must implement and expose. The suggested URL's, are only examples, and you, as an integrator, are free to define your own.

User created notification

Notification that will be send when a new user is created.

Request Body schema: application/json
memberId
string

The memberId of the new user

phoneNumber
string

Phonenumber of the new user

provider
string

Name of the loyalty program owner

Responses

200

Expected http status code.

post /user-create-notification

Production

https://user.storebox.com/user-create-notification

Test

https://test-user.storebox.com/user-create-notification

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",
  • "phoneNumber": "4511111111",
  • "provider": "storebox"
}

User updated notification

User has updated either phonenumber or some parameters

Request Body schema: application/json
memberId
string

The memberId of the new user

phoneNumber
string

Phonenumber of the user

provider
string

Name of the loyalty program owner

parms
Array of objects

Responses

200

Expected http status code.

post /user-update-notifcation

Production

https://user.storebox.com/user-update-notifcation

Test

https://test-user.storebox.com/user-update-notifcation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",
  • "phoneNumber": "4511111111",
  • "provider": "storebox",
  • "parms":
    [
    ]
}

User deleted notification

User has been deleted

Request Body schema: application/json
memberId
string

The memberId of the user

provider
string

Name of the loyalty program owner

Responses

200

Expected http status code.

post /user-delete-notifcation

Production

https://user.storebox.com/user-delete-notifcation

Test

https://test-user.storebox.com/user-delete-notifcation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",