Chaay API Documentation

Introduction

Welcome to the Chaay API. This API allows you to integrate loyalty rewards functionality into your applications, POS systems, and services.

Base URL

https://api.chaay.io/api

Request Format

All requests should be made with Content-Type: application/json header. Request bodies should be valid JSON.

Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

                        // Successful Response
{
    "success": true,
    "data": { ... }
}

// Error Response
{
    "success": false,
    "error": {
        "code": "INVALID_REQUEST",
        "message": "Validation failed"
    }
}
                    

Authentication

The Chaay API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Authentication Types

Type	Usage	Token Lifetime
`Customer JWT`	Customer mobile app	7 days
`Merchant JWT`	Merchant dashboard & app	24 hours
`API Key`	POS integration	No expiry

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Send OTP

Send a one-time password to a customer's phone number for authentication.

POST /auth/customer/send-otp

Sends OTP via WhatsApp or SMS

Request Body

Parameter	Type	Description
`phoneNumber`	string Required	Customer phone number with country code (e.g., +964771...)
`referralCode`	string Optional	Referral code if registering via referral

Example

                        // Request
POST /api/auth/customer/send-otp
{
    "phoneNumber": "+964 771 137 2822"
}

// Response
{
    "success": true,
    "message": "OTP sent successfully",
    "expiresIn": 300
}
                    

Verify OTP

Verify the OTP and receive authentication tokens.

POST /auth/customer/verify-otp

Verifies OTP and returns JWT tokens

Request Body

Parameter	Type	Description
`phoneNumber`	string Required	Customer phone number
`otp`	string Required	6-digit OTP code

Example

                        // Response
{
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
    "expiresIn": 604800,
    "isNewUser": false
}
                    

Customer Profile

GET /customers/profile Auth Required

Get authenticated customer's profile

Response

                        {
    "id": "uuid",
    "phoneNumber": "+964 771 137 2822",
    "name": "Ahmed Ali",
    "email": "[email protected]",
    "tier": {
        "id": "uuid",
        "name": "Gold",
        "pointsMultiplier": 1.5
    },
    "pointsBalance": 2450,
    "lifetimePoints": 5200,
    "referralCode": "AHMED2024"
}
                    

Wallet & Points

GET /customers/wallet/balance Auth Required

Get current point balance

GET /customers/wallet/transactions Auth Required

Get transaction history (paginated)

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)
`type`	string	Filter by type: earn, redeem, bonus, adjustment

Vouchers

GET /vouchers Auth Required

List available vouchers to claim

POST /vouchers/{voucherId}/claim Auth Required

Claim a voucher using points

GET /vouchers/mine Auth Required

Get customer's claimed vouchers

Referrals

GET /customers/referral-code Auth Required

Get or generate referral code

GET /customers/referral-stats Auth Required

Get referral statistics

Response

                        {
    "referralCode": "AHMED2024",
    "totalReferrals": 12,
    "monthlyReferrals": 3,
    "pointsEarned": 600
}
                    

Badges

GET /customer/gamification/badges Auth Required

List all badges the customer has earned, grouped by rarity (Common, Rare, Epic, Legendary, Mythic).

Response

                        {
    "earned": [
        {
            "id": "uuid",
            "code": "first_visit",
            "name": "First Visit",
            "rarity": "common",
            "iconUrl": "https://cdn.chaay.io/badges/first-visit.svg",
            "earnedAt": "2026-04-10T14:22:00Z"
        }
    ],
    "totalEarned": 7,
    "totalAvailable": 10
}
                    

Challenges

GET /customer/gamification/challenges Auth Required

List active challenges with progress for the authenticated customer.

POST /customer/gamification/challenges/{challengeId}/join Auth Required

Opt-in to a challenge that requires manual enrollment.

Streaks

GET /customer/gamification/streaks Auth Required

Get current streaks, longest streak, and available freeze tokens.

POST /customer/gamification/streaks/{streakDefinitionId}/freeze Auth Required

Consume one freeze token to protect a streak from breaking.

Leaderboards

GET /customer/gamification/leaderboard-rank Auth Required

Get the customer's current rank across all active leaderboards (weekly spend, visit count, referrals, etc.).

Response

                        {
    "leaderboards": [
        {
            "id": "uuid",
            "code": "weekly_spend",
            "name": "Weekly Spend",
            "rank": 4,
            "score": 128500,
            "totalParticipants": 1842,
            "resetsAt": "2026-04-28T00:00:00Z"
        }
    ]
}
                    

Merchant Dashboard

GET /merchants/dashboard Auth Required

Get merchant dashboard statistics

Response

                        {
    "totalCustomers": 2847,
    "activeCustomers": 1523,
    "pointsAwarded": 45200,
    "pointsPool": 10000,
    "vouchersRedeemed": 234,
    "returnRate": 0.89
}
                    

Award Points

POST /merchants/points/award Auth Required

Award points to a customer

Request Body

Parameter	Type	Description
`customerId`	string Required	Customer UUID or phone number
`amount`	number Required	Purchase amount for point calculation
`invoiceNumber`	string Optional	Reference invoice number

Merchant Vouchers

POST /merchants/vouchers Auth Required

Create a new voucher

GET /merchants/vouchers Auth Required

List merchant's vouchers

POST /merchants/vouchers/redeem Auth Required

Redeem customer's voucher

POS: Verify Customer

Verify a customer by phone number or QR code scan.

GET /v1/customers/verify API Key

Verify customer identity

Headers

X-API-Key: your_merchant_api_key

Query Parameters

Parameter	Type	Description
`phone`	string	Customer phone number
`qrCode`	string	QR code value from customer app

POS: Award Points

POST /v1/points/award API Key

Award points via POS system

Request Body

                        {
    "customerId": "uuid-or-phone",
    "purchaseAmount": 25.50,
    "invoiceNumber": "INV-001234",
    "timestamp": "2026-01-24T10:30:00Z"
}
                    

POS: Redeem Voucher

POST /v1/vouchers/redeem API Key

Redeem customer voucher via POS

Request Body

                        {
    "voucherCode": "VCHR-ABC123",
    "customerId": "uuid"
}
                    

Response

                        {
    "success": true,
    "voucher": {
        "name": "Free Tea",
        "discountType": "percentage",
        "discountValue": 100
    },
    "redeemedAt": "2026-01-24T10:35:00Z"
}
                    