Developer

User lookup and enrollment using Viking terminals

Description

This is a quickstart quide for using Storebox services with Viking terminals.

For a more indepth introduction please refer to the document DAM Services Storebox Cardlink integration ECR integration notes

APIs involved

Viking API

Flow

Store enrollment

Every new store location has to be registered before first use. This is a one time process that is done in two steps
  1. Request Store token from Storebox (documentation)
  2. Call registerstore through Baxi

Step 1 & 2: Get Store token from Storebox

See documentation. Here is an example using cURL. Username and password are issued by Storebox. 
% curl -u username:password "https://test-dam.storebox.com/v1/authenticate?storeId=my-unique-id-1"
{"token":"eyJ0eSNIP.eyJzdSNIP.KzHE1SNIP"}

Step 3: Register store

Using the token from Step1, execute the following DA framework message using the SendJson function in Baxi.

action value is subject to change and must always be verified in latest Nets terminal documentation.

Request


{
    "da": {
        "ver": "1.0",
        "type": 101,
        "action": 114,
        "ra2dam": {
            "ver": "2.0",
            "requestid": "1231231230",
            "registerstore": {
                "asset": {
                    "template": { "name": "storebox" },
                    "attributes": [
                        {
                            "token": "eyJ0eSNIP.eyJzdSNIP.KzHE1SNIP"
                        }
                    ]
                }
            }
        }
    }
}

Response


{
  "dam2ra":{
    "registerstore": {
      "asset":{
        "attributes":[{"response":"Store registered successfully"}]
      }
    }
  }
}

User lookup

To lookup if a customer is registered in Storebox or an associated customer program, use the following JSON payload in the SendJson function in Baxi.

action value is subject to change and must always be verified in latest Nets terminal documentation.

Request


{
    "da": {
        "ver": "1.0",
        "type": 101,
        "action": 192,
        "ra2t": { "ver": "1.0", "query": [ { "mode": 4 } ] },
        "ra2dam": {
            "ver": "2.0",
            "requestid": "1231231230",
            "getasset": {
                "asset": {
                    "template": { "name": "storebox" },
                    "keys": [
                        {
                            "cardref": "<cardref.001>"
                        }
                    ]
                }
            }
        }
    }
}

Response

{
   "da":{
      "ver":"1.0",
      "type":101,
      "action":192,
      "status":"  5:0",
      "statustext":"OK",
      "dam2ra":{
         "requestid":"1231231230",
         "responseid":"e333542b-a234-4565-a387-63ac4dc0b994",
         "ver":"2.0",
         "getasset":{
            "asset":{
                "id":"1231231230",
                "template":"uuid",
                "keys":[],
                "attributes":[{"payload":" - Solution specific JSON content from Storebox - "}]
            }
         }
      }
   }
}

Loyalty API example

User enrollment

It is possible to enroll a customer directly from the terminal. It is a prerequisite that some kind of customer identifier can be supplied.

This can either be a member id or a phone number, which will be used to activate a consent process.

Get phone number

The terminal can be used to request the phone number from customer.

action value is subject to change and must always be verified in latest Nets terminal documentation.

Request


{
   "da":{
      "ver":"1.0",
      "type":998,
      "action":3,
      "ra2t":{
         "ver":"1.0",
         "query":[{ "id":7, "target":1, "mode":1, "max":8, "min":8 }]
      }
   }
}

Response


{
    "da":{
        "ver":"1.0",
        "type":998,
        "action":3,
        "t2ra":{
            "ver":"1.0",
            "results":[{"id":9,"value":"12345678"}]
        }
    }
 }
Note that the customer will most likely not enter country code on the terminal and the enrollment request require that the phone number is in MSISDN format, so it is up the integrator to make sure that the phone number is in the correct format.

Enroll

When the phone number and/or the member id has been collected, the enrollment request can be made using the following payload, using SendJson in Baxi.

{phone} and {member id} should be replaced with their respective values. Only one of them is required, but both may be supplied.

Note: {member id} is currently not used, but reserved for future use.

action value is subject to change and must always be verified in latest Nets terminal documentation.

Request


{
    "da": {
        "ver": "1.0",
        "type": 101,
        "action": 191,
        "ra2t": { "ver": "1.0", "query": [ { "mode": 4 } ] },
        "ra2dam": {
            "ver": "2.0",
            "requestid": "1231231230",
            "insertasset": {
                "asset": {
                    "template": { "name": "storebox" },
                    "keys": [ { "cardref": "<cardref.001>" } ],
                    "attributes": [
                        {
                            "msisdn": "{phone}"
                        },
                        {
                            "memberno": "{member id}"
                        }
                    ]
                }
            }
        }
    }
}

Response

Per default the response always contains a "posapi" object with card identifiers for the new card for use with receipt delivery through POS API.
Furthermore other API references may be contained depending on the services used from Storebox. E.g. a "cardlinkapi" object or "loyaltyapi" object. The name designates the API that is in play for the customers setup and contains any data that is relevant in response to insertAsset. 


{
  "da" : {
    "ver" : "1.0",
    "type" : 101,
    "action" : 191,
    "status" : "  5:0",
    "statustext" : "OK",
    "dam2ra" : {
      "requestid" : "1231231230",
      "responseid" : "6b9e963e-eec2-4615-a20f-f47d60185c8e",
      "ver" : "2.0",
      "insertasset" : {
        "asset" : {
          "template" : "92debb63-0cc5-4570-aeaf-a3f9fb6c0563",
          "keys" : [ {
            "cardref" : "f37388e0-0a1f-11eb-b596-5c4242535400"
          } ],
          "attributes" : [ {
            {
                "payload": {
                    "id": "800unxobgxyrguqqv11ankz0vsuy2p5w",
                    "posapi": {
                        "userId": [
                            {
                                "type": "pan",
                                "value": "f37388e0-0a1f-11eb-b596-5c4242535400"
                            }
                        ]
                    },
                    "cardlinkapi": {
                        "...": "..."
                    }
                }
            }
          } ],
          "id" : "92debb63-0cc5-4570-aeaf-a3f9fb6c0563"
        }
      }
    }
  }
}

Send a receipt to the new user, by inserting the userId, along with any other custom user ids in the POS API receipt payload, like this example 


{
    "userId" : [
        {
            "type" : "pan",
            "value" : "f37388e0-0a1f-11eb-b596-5c4242535400"
        },
        ...
    ],
    ...
}

FAQ

What are the technical requirement?

The following requirements must be in place to use the DAM services from an ECR application;

Home Privacy PCI DSS API Status
© 2024 Storebox