Redeem Points at Checkout

Redemption lets a customer spend their points to reduce what they pay. It builds directly on Track Orders: you add a hold step that locks the points, then submit the same order call with a reference to that hold. The hold prevents double-spending and guarantees the points are reserved for this transaction only.

If you haven’t implemented Track Orders yet, do that first. Redemption is the order call plus one extra step.

The Redemption Flow

Check the balance

Retrieve the customer’s balance to confirm they have enough points to redeem.

Hold the points

Reserve the redemption amount with the Hold Points API. This returns a holdReference.

Submit the order with the hold reference

Place the order using the Track Orders call, adding a redemption block that references the hold.

Step 1: Hold the Points

This reserves the points temporarily before checkout completes:

curl -X POST 'https://api.gameball.co/api/v4.0/integrations/transactions/hold' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "12345",
    "transactionTime": "2025-10-19T12:00:00Z",
    "pointsToHold": 100
  }'

{
  "customerId": "12345",
  "holdAmount": "10.00",
  "holdEquivalentPoints": 100,
  "holdReference": "HOLD-abc123"
}

Holds are time-limited (typically 10 minutes). If the order isn’t completed in time, the points are automatically released back to the customer. Don’t reuse or delay using a holdReference.

Step 2: Submit the Order with the Redemption

This is the standard Track Orders call with one addition, a redemption block carrying the hold reference. Note that totalPaid reflects the discounted amount:

curl -X POST 'https://api.gameball.co/api/v4.0/integrations/orders' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "12345",
    "orderId": "ORD000123",
    "orderDate": "2025-10-19T12:10:00Z",
    "totalPaid": 90.00,
    "totalPrice": 100.00,
    "redemption": {
      "pointsHoldReference": "HOLD-abc123"
    }
  }'

{
  "orderId": "ORD000123",
  "customerId": "12345",
  "pointsRedeemed": 100,
  "pointsEarned": 9,
  "rewardedPoints": 9,
  "status": "completed"
}

Behind the scenes, Gameball verifies the hold reference, deducts the redeemed points, and rewards new points based on the amount actually paid after redemption, then updates the customer’s redemption and earning history.

Tips & Gotchas

totalPaid must reflect the discounted value after applying the held points.
totalPrice should always be the original order value before discounts.
If the customer cancels or abandons the transaction, release the hold using the Release Hold API.

Redemption Methods

Standard
QR Code
Virtual Pass

The flow above, where the customer is identified by customerId (mobile number, email, or CRM ID) and you hold then redeem against their balance.

Instead of typing a phone number, the cashier scans a QR code the customer shows from their Gameball widget/app or their Virtual Pass. The QR encodes both who the customer is and a one-time security token, so the customer is identified and verified in a single scan, no separate lookup needed.

How it works

Scan the QR code

The scanned value is a single string that joins the customer ID and a rotating 6-digit hash.

Split the value

The last 6 digits are always the hash. Everything before them is the customerId. There’s no separator, so split by position.

Hold points with the hash

Pass both the parsed customerId and the hash to the Hold Points call. The hash proves the request is genuine.

Submit the order

Complete the order with the returned holdReference, exactly like the Standard flow.

Anatomy of the scanned value

Take the example value mobile_966500001234123456:

Part	Value	How to extract it
`customerId`	`mobile_966500001234`	Everything except the last 6 characters
`hash`	`123456`	The last 6 characters

Hold points with the hash

Add the hash field to the Hold Points request:

curl -X POST 'https://api.gameball.co/api/v4.0/integrations/transactions/hold' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "mobile_966500001234",
    "transactionTime": "2025-10-19T12:00:00Z",
    "pointsToHold": 1000,
    "hash": "123456"
  }'

The hash is a rotating, single-use security token, it changes regularly and expires. Only send it in the Hold Points call, and never store or reuse an old hash. If a scan fails validation, ask the customer to refresh their QR code and scan again.

The same hash can also be generated server-side via the Get Customer Hash API if you need to validate a customer without a live scan.

​The Redemption Flow

​Step 1: Hold the Points

​Step 2: Submit the Order with the Redemption

​Tips & Gotchas

​Redemption Methods

​How it works

​Anatomy of the scanned value

​Hold points with the hash

The Redemption Flow

Step 1: Hold the Points

Step 2: Submit the Order with the Redemption

Tips & Gotchas

Redemption Methods

How it works

Anatomy of the scanned value

Hold points with the hash