> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started & API Setup

> Prerequisites, API credentials, and core concepts for POS integration with Gameball

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
```

<Info>
  Switch between Test and Live environments by using your Test or Live API Keys. The base URL stays the same for both.
</Info>

<Note>
  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.
</Note>

### 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:

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/balance' \
    -H 'APIKey: YOUR_API_KEY' \
    -H 'SecretKey: YOUR_SECRET_KEY'
  ```
</RequestExample>

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

<Warning>
  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.
</Warning>

* 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

<Warning>
  Always use HTTPS for all API calls. Never send API credentials over unencrypted connections.
</Warning>

* 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](/installation-guides/v3/pos/customer-management) - Get or create customers at checkout
2. [Show Customer Balance](/installation-guides/v3/pos/customer-balance) - Retrieve and display loyalty information