Using Virtual ID

Problem

• Customers aren’t able to securely and discreetly identify themselves at your in-store POS

• POS clerks aren’t able to easily verify the person approaching them is who they claim they are

Pre-requisites

• Your own physical store/s with a Point of Sale (POS) System at checkout points

• Integrate your POS system with Gameball APIs

• Your store’s own mobile application for users to download and login to their accounts

• QR Code readers at your POS checkout point, that are able to scan mobile screens

If you don't have a mobile application for your customers, Gameball got you covered! Check Gameball's Virtual Card.

Solution

• Create and render a QR code within your mobile application, for each customer to present; discreetly identifying themselves. This QR code includes:

  • The customer’s Gameball unique identifier: playerUniqueId

  • The customer’s rotating secret code: hash, for the POS system to verify the customer’s authentic identity

• Scan the customer’s QR code value into your in-store POS system, then parse the customer’s playerUniqueId and hash, this will allow your POS to:

  • Identify the customer; by bringing up their profile and balance using playerUniqueId & Customer Balance API

  • Securely verify the customer; by adding hash to Hold Points & Order APIs request bodies from your POS; verifying the customer’s identity with any requests affecting their points balance

Scenario

So, let's start by saying you have your own clothing store “STYL Outfits”, and your customer John Doe, wants to do some clothes shopping at your local shop. John walks in, shops around, and picks his favorite products, finally he approaches the in-store POS checkout point to complete their purchase.

You are building your amazing brand and are keen on making sure to engage your customers, reward them, and ultimately redefine their shopping experience. So, you integrate your in-store POS with Gameball APIs.

Now your POS clerks are ready to help your customers in-store to: check their current balance, redeem points, create an order that adds up to their points, etc...

You also developed your own mobile application “STYL”, for providing your customers with a complete experience in-store, and right in their pockets.

Holding nothing back, you have integrated your mobile application with Gameball APIs too, where your customers can access their accounts, place online orders, check their points, watch their current progress, etc…

Now John will approach your in-store POS, to purchase a t-shirt he likes. Using your mobile app, he checks that he has a balance of 2000 points, and wants to use some of his points to get a discount on that t-shirt. He also checks your app to find that each 1 point is worth $0.01 USD.

Nevertheless, your POS clerk will require the customer's identity to be able to bring up the customer's profile and balance.

Hence we face the following issue, asking customers to go through the hassle of proving identification - reciting their phone numbers/emails, or sharing their personal details - is neither secure nor would be considered a smooth shopping experience.

You want your customers to be able to seamlessly and securely identify themselves as they come up at your in-store POS. Furthermore you want to protect your POS clerks from having to jump through hoops to actually verify that the customer is actually authentic regarding their identity, and not to have to detect any fraudulent attempts using only their personal sensors. This could easily turn problematic, leading to many unwanted issues, and ruining your customers’ experience shopping at your store.

Through this tutorial, we’re going to propose a solution for your use case to achieve a seamless, instantaneous and secure virtual identification once your customer reaches your POS clerk.

This solution entails that each customer will have their unique QR code. As customers approach the in-store POS, they will be asked to open your mobile application “STYL”, and present their in-app QR Code to the QR Code scanner attached to your POS, which will scan to identify the customer securely and discreetly.

How to generate a QR Code in your mobile application

You can follow the following steps to generate a QR code for your customer:

GET https://api.gameball.co/api/v3/Integrations/player/{playerUniqueId}/hash

1. Retrieve your customer’s Gameball Hash

   • Send a request to Gameball’s Customer Hash API, which will return a Hash

     GET https://api.gameball.co/api/v3/Integrations/player/{playerUniqueId}/hash

   • The Hash is a six digits temporary secret which is customer unique, and is always changing for each customer based on their activity and transactions.

     // Let's assume the customer’s Unique Identifier is the following:
     playerUniqueId=01000100010
     
     
     GET https://api.gameball.co/api/v3/Integrations/player/01000100010/hash
      
     // Response Body
     {
         ...
         "hash": "123456"
         ...
     }

     Notice that the Customer Hash API is a secure API, that could only be accessed using your Secret Key in the header. Refer to docs for more info.

2. Generate the customer’s QR Code Value The QR code value will be the concatenation of both your customer’s playerUniqueId followed by 6 digits that resemble their current Hash; in the following format: playerUniqueIdHash. For example: If your customer’s unique identifier is: 01000100010, and their current hash is 123456. The QR code value will be: 01000100010123456

3. Draw the customer’s QR Code Now you are able to generate a QR Code in your Mobile Application, for your physical POS to scan in-store, and immediately identify the customer using:

   • The customer's unique identifier: playerUniqueId

   • The customer's current hash: Hash

     

Make sure to call the Customer Hash API every time the user opens their QR Code. Since hash is a rotating secret and changes with every customer’s transaction.

Creating the QR code is a very simple operation, we'll be providing an example below in Node.js, using the qrcode package @ https://www.npmjs.com/package/qrcode

# Make sure to install qrcode & axios
npm install qrcode axios --save

// The code below contains several hard coded values
// which are set here ONLY for demonstration purposes
const path = require('path');
const axios = require('axios');
const QRCode = require('qrcode');

// Set Gameball Keys as headers for request
// DISCLAIMER: Gameball Keys are supposed to be stored appropriately as secrets
const HEADER = {
    headers: {
        apiKey: '807b041b7d35425988e354e1f6bce186',
        secretKey: 'klmb041b7d354259l3u4ft35e1q2r3703'
    },
};

// Player Unique Id should already be a dynamic variable in your application
let playerUniqueId = 'player456';

// Send out a request to Gameball Player Hash API, and wait for response
axios
    .get(`https://api.gameball.co/api/v3/Integrations/player/${playerUniqueId}/hash`, HEADER)
    .then((response) => {
        // Parse hash from response json
        let hash = response?.data?.data?.hash;

        // The QR code will resemble a string containing both player unique id and hash
        // For example: player456112233
        let code = playerUniqueId + '' + hash;
       
        // A QR code image is generated in the same directory, 
        // with the playerUniqueId as the file name
        QRCode.toFile(path.join(__dirname, `${playerUniqueId}.png`), code, (err) => {
            if (err) throw err;
        });
    })
    .catch((e) => {
        console.error(e)
    });

Integrate your POS with QR Code

As users approach the POS clerk in-store, the clerk will scan the customer’s QR code from your mobile application on the customer’s device. Following this, the POS is expected to identify the customer and verify them while submitting orders or claiming/redeeming points on their behalf; this is simply done via the following steps.

Start to Step 1: POS QR Code reader scans the customer’s QR code

The QR Code value is read as input to the POS using the following format playerUniqueIdHash.

1. The last 6 digits in the QR code value is the customer’s current Hash

2. The remaining characters resemble the customer’s playerUniqueId Below is a simple snippet showing how you could parse the QR Code Value

...
// This is the string read by QR Code scanner / Bar Code reader
var inputCode = '01000100010123456';

// Only get last 6 characters in the inputCode string
var hash = inputCode.slice(-6);
// hash: 123456

// Get all characters in inputCode string except the last 6
var playerUniqueId = inputCode.slice(0,-6);
// playerUniqueId: 01000100010
...

Step 2 to 3: POS fetches the player details and balance

POS now has the details required to identify the player, process any requests with Gameball using the playerUniqueId, and verify the customer’s identity using their latest Hash.

The POS will use the playerUniqueId to bring up the customer’s profile and balance using APIs like Player Balance API

GET https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/balance

// Response body
{
    "pointsBalance": 2000,
    "pointsValue": 20,
    ...
    "currency": "USD",
    "pointsName": "Points"
}

Step 3 to 4: POS Clerk submits hold request for customer

The POS clerk can validate the customer’s request to redeem their current points. Let’s assume the customer wants to redeem a 1000 points, well the POS will attempt to hold the agreed points using the Hold Points API.

To securely ensure the points hold is being done on behalf of a verified customer, the POS will need to add the customer’s current hash value to the Hold Points API request body.

Gameball verifies the received hash matches the customer’s current hash, and ensures the customer has enough points to proceed with the hold request. In response, it will send back to the POS:

1. holdReference: a reference string to the successful hold created

2. amount: the amount of points on-hold converted to their monetary value

3. holdPoints: the amount of points on-hold converted from the sent monetary value

POST https://api.gameball.co/api/v3.0/integrations/transaction/hold

// Request Body
{
"playerUniqueId":"01000100010",
"holdPoints": 1000,
"amount": 10,
"transactionTime":"2019-09-21T16:53:28.190Z",
"hash": "123456"
}

// Response Body
{
"playerUniqueId":"01000100010",
"amount": 10,
"holdPoints": 1000,
"holdReference":"ref_12343ds"
}

Step 5 to 6: POS Clerk completes the order checkout for customer

The POS will send the Order details through Gameball's Order API, along with the holdReference "ref_12343ds" received from the Hold Points API. This ensures the points are deducted properly for the discounted order. To securely verify the customer’s order to their accounts, the POS should add the customer’s current hash value to the Order API request body.

POST https://api.gameball.co/api/v3.0/integrations/order

REQUEST -
{
"playerUniqueId":"01000100010",
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "100",
"totalPaid": "90",
...
"redeemedAmount": 10,
"holdReference": "ref_12343ds",
"guest": false,
"hash": "123456"
}

RESPONSE -
{
"playerUniqueId": "01000100010",
"redeemedPoints": 1000,
"rewardedPoints": 90,
...
}

Gameball verifies the received hash matches the customer’s current hash, and ensures the hold reference sent is active and still valid for the customer. If successful, the Order API will respond with success, completing the customer’s order at your store.

If the customer's hash is incorrect, Gameball will reject the POS attempts to create an order or hold points to this customer’s identifier preventing any fraudulent attempts.

POS UI Tips

1. Create elements in your POS UI to assist your clerks with easily identifying the customer’s details, available points, etc…

   1. Before Scanning Virtual Card

      
   2. After Scanning Virtual Card Once the POS Clerk scans the customer’s QR Code, and fetches the customer’s details using Gameball APIs, the POS display should automatically bring up the player details as shown below

      
2. After the discount being successfully applied The discount is now applied on the total order, and the points to be redeemed are now on-hold. Always make sure to provide the POS clerk with a way to cancel the held points and remove the points discount from the order.

   

There you have it, the full experience in your physical store, where customers could check your mobile application as they leave your store, to see how many points they've received, if they leveled up, and their progress in your engagement program. This completes the full cycle, as if they're using your mobile application next time they engage with your brand they are still going through the same experience they had at your physical store and vice-versa.