Gameball Developers Guide
v3.0
v3.0
  • Introduction
  • What's New in V3.0
  • Installing Gameball
    • Web
      • Show Gameball Customer Widget
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • iOS
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • Android
      • Getting Started
      • Initialize Gameball SDK
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • React Native
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
      • Migration from v1 to v2
    • Flutter
      • Getting Started
      • Initialize Gameball SDK
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Referrals
      • Go-Live Checklist
    • Generic Mobile App
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
    • Retail & Modern POS
      • Initialize Gameball Customer Profile
      • Track Orders & Cashback Reward
      • Track Refunds
      • Enable Redemption
        • Prepare POS for Redemption
        • Using Virtual ID
          • Using Virtual Card
  • REST API
    • Overview
      • Server-Side SDKs
    • Authentication
    • API Reference
      • Customer
      • Event
      • Transactions
      • Order
      • Coupons
      • Leaderboard 👑
      • Notifications 👑
      • Configurations 👑
      • Batches 👑
        • Batch Operations Data
      • OTP
      • Partner 🤝
        • Client 🤝
        • Redemption Rule 🤝
        • Cashback Rule 🤝
    • Webhooks
      • Notifications Webhook
      • Customer Profile Webhook
    • Errors
    • Object Reference
  • Tutorials
    • Build Custom UI Elements 👑
      • Display Reward Campaign Progress
      • Show VIP Tiers
      • Show Customer Points Balance
      • Build Leaderboards
      • Show Notifications Inbox
      • Adapt UI to Configurations
      • Advanced UI Techniques
        • Increase Sales with Cashback UI Elements
        • Derive Engagement with Rewards Campaigns UI Elements
    • Tracking Customer Events
    • Build your Own Notification System
    • Checkout Integration Example
    • Redemption Integration Options
      • Redeem with coupon system
        • Integrate your coupon system
          • Example using e-commerce platform(WooCommerce)
          • Example using a custom coupon system
        • Build couponing experience
          • Using Gameball widget
          • Build custom experience
            • Showing customers available points
            • Allowing customers to create coupons
            • Apply the discount code to your cart
        • Coupon integration reference
      • Redeem with direct debt
        • Get customers points balance
        • Redeem customer points
  • Third Party Integrations
    • Segment Integration
Powered by GitBook
On this page
  • Problem
  • Pre-requisites
  • Solution
  • Scenario
  • How to generate a QR Code in your mobile application
  • Integrate your POS with QR Code
  • POS UI Tips
  1. Installing Gameball
  2. Retail & Modern POS
  3. Enable Redemption

Using Virtual ID

PreviousPrepare POS for RedemptionNextUsing Virtual Card

Last updated 1 year ago

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

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

Solution

  • . 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

  • , 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

    • 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"
          ...
      }

  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 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.

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

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

Make sure to call the 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
Gameball's Virtual Card.
Create and render a QR code within your mobile application, for each customer to present; discreetly identifying themselves
Scan the customer’s QR code value into your in-store POS system
Customer Hash API
Customer Hash API
Customer Hash API