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.

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:
basicAuthapiKeyAuth
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

storeId
string

Indicates what store sent the signup request to Storebox. This value will only be used to include in the verification SMS, if one is sent.

Responses

Request samples

Content type
application/json
{
  • "phonenumber": "4511111111",
  • "truncatedPan": "457100XXXXXX0001",
  • "token": "2797aa22047e89e0b39c1626b1be53cf246051b4927f2be7108bf5476edf4937",
  • "payment": true,
  • "storeId": "SB-10001"
}

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:
basicAuthapiKeyAuth
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

Request samples

Content type
application/json
{
  • "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:
basicAuthapiKeyAuth
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

Request samples

Content type
application/json
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",
  • "smsType": 1
}

Get link code information

A link code is a reference to the signup data Storebox recieves upon enrollment initiation. Before the enduser is enrolled, mandatory information and terms accept should be collected. Once collected from the enduser the link code can be used to enroll the enduser.

Authorizations:
basicAuthapiKeyAuth
path Parameters
linkCode
required
string
Example: p7hy9

The linkCode created by Storebox during verification preparation

Responses

Response samples

Content type
application/json
{
  • "provider": "Storebox",
  • "phoneNumber": 4512345678,
  • "linkCode": "cnhocnfz4d",
  • "storeId": "SB-10001",
  • "created": "2014-05-14T15:22:11Z"
}

Link code exists

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

Authorizations:
basicAuthapiKeyAuth
path Parameters
linkCode
required
string
Example: p7hy9

The linkCode created by Storebox during verification preparation

Responses

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:
basicAuthapiKeyAuth
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

Request samples

Content type
application/json
{
  • "memberId": "6fpw801mmb081vrn3jvqnr293v66c2ix"
}

Response samples

Content type
application/json
{
  • "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:
basicAuthapiKeyAuth
path Parameters
userId
required
string
Example: 0467q4wqp7hyyxei3amxauz808vudi5x

The user id from the OTP process

Responses

Response samples

Content type
application/json
{
  • "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:
basicAuthapiKeyAuth
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

phonenumberValid
boolean

Set this to true to avoid starting an OTP flow. It is then up to the caller that the phone number is verified.

Array of objects

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

Responses

Request samples

Content type
application/json
{
  • "phonenumber": "string",
  • "phonenumberValid": true,
  • "parms": [
    ]
}

Delete user

Delete the user with the supplied id.

Authorizations:
basicAuthapiKeyAuth
path Parameters
userId
required
string
Example: 0467q4wqp7hyyxei3amxauz808vudi5x

The user id from the OTP process

Responses

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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

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

Response samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "phonenumber": "4511111111",
  • "otp": "1234"
}

Response samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "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

Array of objects

Responses

Request samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "memberId": "xy4zj61clts8x00kfwpra9y0fiq79a2f",
  • "provider": "storebox"
}