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
  • Update your POS system UI
  • Update the Order API
  1. Installing Gameball
  2. Retail & Modern POS
  3. Enable Redemption

Prepare POS for Redemption

PreviousEnable RedemptionNextUsing Virtual ID

Last updated 1 year ago

In order to prepare for redemption through your POS, the following considerations has to be taken to provide seamless experience for both the customer and the POS clerk.

  1. to show and verify the customer points balance

  2. to include the redemption information

Update your POS system UI

When integrating the Gameball with your POS system. You will likely need to update your POS user interface (UI) to include the the customer's loyalty balance information . Here are some general steps to follow for updating your POS UI:

Identify the UI elements that need to be updated

The first step is to identify the UI elements in your POS system that need to be updated to display the customer's loyalty balance. This might include adding a new field or label to the customer profile or transaction screens, or modifying existing fields to display both the transaction amount and the loyalty balance.

Utilizes Gameball's Customer Balance API

Below is a sample request and response to get the balance of customer with identifier player456

GET - https://api.gameball.co/api/v3.0/integrations/player//balance

// Response Body
{
    "pointsBalance": 11500,
    "pointsValue": 115a
    "pendingPoints": 200,
    "pendingPointsValue": 2,
    "totalPositivePoints": 12500,
    "totalPositivePendingPoints": 135,
    "totalNegativePoints": 1000,
    "totalNegativePendingPoints": 20
    "currency": "USD",
    "pointsName": "Points"
}

Once you have retrieved the customer's loyalty balance, you can display it in your POS system. The exact method for displaying the balance will depend on your POS software, but you might consider adding a dedicated loyalty balance field or displaying the balance alongside the customer's name or other identifying information.

Determine the identification mechanism

  1. Direct communication between POS clerk and customer

With this method, the POS clerk asks the customer for their unique identifier, such as their email address or phone number, and manually enters it into the POS system. The system then uses this identifier to retrieve the customer's loyalty balance and apply any relevant discounts or rewards.

This method requires a bit more effort on the part of the POS clerk and the customer, but it can be useful in situations where the customer does not have a virtual card or the card is not compatible with the POS system.

With this method, the customer presents a virtual loyalty card on their mobile device, which the POS system scans using a barcode or QR code reader. The system then uses the information encoded in the card to retrieve the customer's loyalty balance and apply any relevant discounts or rewards.

Update the Order API

Let take the below example senario

  1. Customer approaches your in-store POS to purchase a $100 product

  2. Customer requests redeeming $10 worth of his points from this product

  3. Your POS clerk requests the customers identification (Mobile Number, Full Name, Email), your POS then identifies the customer's playerUniqueId based on your configuration

  4. POST - https://api.gameball.co/api/v3.0/integrations/order
    
    REQUEST BODY -
    {
      "playerUniqueId":"player456",   
      "orderId": "6253e03b",
      "orderDate":"2019-09-21T16:53:28.190Z",
      ...
      "totalPrice": "100",
      "totalPaid": "90",ava
      "redeemedAmount": 10
      ...
    }
  5. Gameball will verify if the customer have enough points worth $10 to redeem or not.

    • YES - the order request will respond successfully (200 Status Code)

    • NO - the order request will respond with an error (500 Status Code)

Using Hold Approach

  • Ensures the customer's balance is legible for redeeming the requested amount before submitting the customer's order

  • Holds the equivalent points to protect you from any fraudulent attempt of using points at the same time from different outlets

We're going to follow the same first 4 steps from the Direct Approach., then once the customer's balance is identified (Step 4):

  1. POST - https://api.gameball.co/api/v3.0/integrations/transaction/hold
    
    REQUEST BODY - 
    {
       "playerUniqueId":"player456",
       "amount":10,
       "transactionTime":"2019-09-21T16:53:28.190Z",
    }
    
    RESPONSE -
    {
       "playerUniqueId":"player456",
       "amount":10,
       "holdPoints":1000
       "holdReference":"ref_12343ds"
    }

  2. Gameball converts the claimed amount $10 to Gameball points (ex: 1000 point), then checks if the customer has enough points to redeem 1000.

    • YES - a hold reference will be created ref_12343ds and the hold request will respond successfully (200 Status Code)

    • NO - the order request will respond with an error (500 Status Code)

  3. POST - https://api.gameball.co/api/v3.0/integrations/order
    
    REQUEST BODY -
    {
      "playerUniqueId":"player456",   
      "orderId": "6253e03b",
      "orderDate":"2019-09-21T16:53:28.190Z",
      ...
      "totalPrice": "100",
      "totalPaid": "90",
      "holdReference": "ref_12343ds",
      ...
    }
    
  4. Gameball will verify the holdReference sent in the Order API, then checks if the hold reference is valid and active for the customer's playerUniqueId.

    • YES - the order request will respond successfully (200 Status Code)

    • NO - the order request will respond with an error (500 Status Code)

Your in-store POS can utilize Gameball's to fetch the customer's point balance. The Customer Balance API retrives the balance for the player using playerUniuqeId which is the identifier your choose to use to identify your customers.

When integrating the Gameball with your POS system, customer identification can be done in a variety of ways, including direct communication between the POS clerk and the customer or by . Here's a brief overview of these two methods:

Now that you have started with enabling the redemption. You need to do some update on the implemented to including the redemption information if any. The update of the Order call will automaticly handles the deduction of points from the customer's points balance.

Your in-store POS utilizes Gameball's and playerUniqueId to fetch the customer's point balance, for the POS clerk to check the customer's balance and verify their legibility to the requested discount.

The POS clerk approves and proceeds with the customer's request, by submitting the order on your in-store POS, which submits this order to Gameball via as follows:

Order API can include the redeemption information directly or a hold reference of a hold points request that has been requested. This approach works if you're looking for a safer measure to insure the deduction of points. Your POS can easily achieve this flow by first holding the requested amount via , then when successful submit the customer's order via with the approved discount.

The POS clerk approves and proceeds with the customer's request, by claiming the requested amount $10 via your in-store POS, which submit a to Gameball.

If successful, your POS should show that the points are held successfully. Then the POS clerk could proceed with submitting the customer's order via .

virtual card scanning
Virtual card scanning
Order API call implemented
Order API
Order API
Order API
Update your POS system UI
Update the integrated Order API
Customer Balance API
Customer Balance API
Hold Points API
Hold Points Request