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

# How Do I Get Started and Set Up the API for Gameball POS (v4)?

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

> [!NOTE]
>
> Switch between Test and Live environments by using your Test or Live API Keys. The base URL stays the same for both.

> [!NOTE]
>
> This is the **v4 SDK generation** of the installation guides. The POS integration is API-only and uses Gameball's **`api/v4.0`** REST endpoints. The SDK version (`v4`) and the API version (`v4.0`) are independent, so the POS steps are the same in every SDK generation.

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

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

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.