Skip to main content
This page covers everything you need before writing your first call: what the integration delivers, how to authenticate, and how to choose a customer ID that works across every channel.

​
What You’ll Build

By the end of this guide, your team will be able to:
  • Identify customers at checkout and register new ones automatically
  • Reward purchases with points in real time
  • Redeem points for discounts securely, with or without a mobile app
  • Refund orders while keeping point balances accurate
The guide is modular and use-case driven, so you can implement each step based on your business needs, platform constraints, and customer behavior.

​
Environment Setup

​
Base URL

All API requests use the same base URL for both Test and Live environments: 
https://api.gameball.co/api/v4.0
Switch between Test and Live environments by using your Test or Live API Keys. The base URL stays the same for both.
This is the v3 SDK generation of the installation guides, but the POS integration is API-only and uses Gameball’s api/v4.0 REST endpoints. The path version (v3) and the API version (v4.0) are independent, you’re in the right place.

​
API Credentials

Retrieve your API Key and Secret Key from the Gameball Dashboard: Dashboard Path: Settings → Account Integration → API Keys You’ll need:
  • API Key: Your Gameball API key
  • Secret Key: Your Gameball API secret

​
Authentication

Every request must include your credentials as headers: 
curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/balance' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY'

​
Choosing Your Customer ID

The customerId is the single most important decision in your integration. It’s the unique key that ties every order, redemption, and reward to the right person.
Use a persistent, unique identifier that is the same across POS, web, and app, for example a normalized mobile number (mobile_966500001234) or a CRM ID. If POS and online use different IDs for the same shopper, their loyalty balance will be split across two profiles.
  • Pick an identifier you can reliably collect at the POS (mobile number or email is most common).
  • Keep the format consistent everywhere, the same customer must always resolve to the same customerId.
  • This single ID is referenced by every other page in this guide.

​
Security Best Practices

Always use HTTPS for all API calls. Never send API credentials over unencrypted connections.
  • Store API credentials securely in your POS system configuration
  • Never expose API keys in client-side code or logs
  • Rotate API keys periodically for enhanced security
  • Use hash validation for QR code-based redemptions

​
Next Steps

  1. Identify the Customer - Get or create customers at checkout
  2. Show Customer Balance - Retrieve and display loyalty information