Prepare POS for Redemption

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

1. Update your POS system UI to show and verify the player points balance

2. Update the integrated Order API 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 Player Balance API

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

Below is a sample request and response to get the balance of player 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

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 virtual card scanning. Here's a brief overview of these two methods:

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.

2. Virtual card scanning

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

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

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. Your in-store POS utilizes Gameball's Player Balance API and playerUniqueId to fetch the customer's point balance, for the POS clerk to check the player's balance and verify their legibility to the requested discount.

5. 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 Order API as follows:

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

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

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 your looking for a more safe mesure to insure the deduction of points. Your POS can easily achieve this flow by first holding the requested amount via Hold Points API, then when successful submit the customer's order via Order API with the approved discount.

• 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 player's balance is identified (Step 4):

1. 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 Hold Points Request to Gameball.

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

   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)