Skip to main content

​
Redeem Points

Enable customers to redeem their earned points for discounts or rewards inside your Android application. Redemption always follows a backend-validated flow to ensure accuracy, prevent fraud, and guarantee correct point deductions.
For a full end-to-end explanation of redemption logic, validation, flows, and backend responsibilities, see the Redemption Integration Tutorial.

​
How Redemption Works

1

Check Customer Balance

Fetch the customer’s available and pending points to determine whether redemption is allowed.
2

Customer Initiates Redemption

The customer taps a “Redeem” action in your app (checkout, cart, wallet screen, etc.).
3

Backend Performs Validation

Your backend validates eligibility and calls the Gameball Redeem API to create a redemption transaction.
4

Apply Discount & Update UI

Your backend returns the final result (approved or rejected), then the app updates the UI accordingly.

​
1. Get Customer Points Balance

Use the Android SDK to retrieve the customer’s balance before initiating any redemption. 
GameballApp.getInstance(context).getCustomerBalance(
    "customer-123",
    object : Callback<CustomerBalance> {
        override fun onSuccess(balance: CustomerBalance) {
            val availablePoints = balance.availablePoints
            val pendingPoints = balance.pendingPoints
            // Display balance to the user
        }

        override fun onError(error: Throwable) {
            // Handle error
        }
    }
)

​
2. Backend-Validated Redemption (Required)

All redemption actions must be performed through your backend. Your backend must:
  1. Verify the customer has sufficient available points
  2. Call the Redeem API
  3. Apply the resulting discount or credit to the order, if applicable
  4. Return the success/failure response to the Android app
Redemption must never be performed directly from the client. Always validate and execute via your backend to prevent fraud.

​
3. Trigger Redemption from Your Android App

fun redeemPoints(pointsToRedeem: Int) {
    yourBackendAPI.createRedemption(
        customerId = "customer-123",
        points = pointsToRedeem
    ).enqueue(object : Callback<RedemptionResponse> {

        override fun onSuccess(response: RedemptionResponse) {
            if (response.success) {
                // Show success message
                // Update wallet balance
                // Apply discount to order/cart
            } else {
                // Show backend error message to the user
            }
        }

        override fun onError(error: Throwable) {
            // Handle network or server error
        }
    })
}

​
4. E-Commerce Checkout Redemption

For checkout scenarios, redemption is typically embedded inside the Order API payload. This lets you apply both:
  • The redeemed points
  • The resulting discount value

​
Example:

val order = OrderRequest.builder()
    .orderId("order-123")
    .customerId("customer-123")
    .amount(149.99)
    .currency("USD")
    .redeemedPoints(500)      // Points to redeem
    .discountAmount(50.0)     // Discount value based on points
    .build()
This method is ideal for e-commerce flows where redemption happens at checkout.
Your backend should pass the calculated redeemed points and discount amount into this request.

​
Summary of When to Use What

Wallet Redemption (Standalone)

Use when the user redeems points outside checkout
→ You must call the Redeem API from your backend.

Checkout Redemption (Order API)

Use when redemption is applied directly to an order during checkout

→ Pass redeemedPoints + discountAmount inside OrderRequest.