PlaySuper API Reference

Use the PlaySuper REST API to integrate rewards directly into your application without an SDK. This guide walks through creating players, identifying them on each call, distributing and deducting coins, listing rewards and purchasing them, in the order you will typically call them.

Prerequisites

• A Game API key from the PlaySuper Console. See API keys below for what the key looks like and which host it works against.
• Your coin ID from the console's Coins section, linked to your game.
• A tool or library for making HTTP requests (curl, fetch, Axios).

API keys

One key does everything on this site. You will see it under a few names.

A key is bound to its environment. Sending a test key to api.playsuper.club (or a live key to dev.playsuper.club) returns 401 Invalid API key. Base URLs, store URLs and the US region hosts are listed in Getting Started.

Response envelope

Every JSON response is wrapped in a standard envelope:

{
  "data": { "...": "the response payload" },
  "statusCode": 200,
  "message": "Success",
  "requestId": "9f6b0e0e-1234-5678-90ab-cdef12345678",
  "timestamp": "2026-07-21T10:30:00.000Z"
}

The response examples in this guide show only the data payload. Two things to know:

• Paginated endpoints (/rewards, /player/orders) return their own { data, meta } or { data, metadata } object as the payload, so the list is at response.data.data and the page info at response.data.meta or response.data.metadata. The examples below show that inner object.
• The login endpoint, POST /player/login/federatedByStudio, is the exception: it returns its body directly, without the envelope.

Errors are not wrapped in data. They come back as { "statusCode": 400, "message": "...", "error": "Bad Request" }.

Step 1: Create a player

Register the player with PlaySuper using your game's internal ID for them. Do this once per player, before the first login:

curl -X POST https://api.playsuper.club/player/create-with-uuid \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "uuid": "your-unique-player-id"
  }'

Response 201:

{
  "message": "Player created successfully",
  "playerId": "d2f1a3b4-5678-90ab-cdef-1234567890ab"
}

This endpoint is find-or-create: calling it again with the same UUID returns the existing player, so it is safe to call on every app launch.

Step 2: Identify the player on each call

Every player-scoped call identifies the player in one of two ways.

Option A: the x-game-uuid header. Send the same UUID from Step 1 on every request:

x-game-uuid: <your-game-player-id>

This is the simplest option for server-to-server calls. The distribute, deduct and purchase endpoints find or create the player from this header, so with x-game-uuid you can go straight to Step 3.

Option B: a Bearer token. You need a token when a player-facing surface must act as the player, for example to open the store in a WebView (see the WebView Integration guide) or to call /player/profile. Get one with federated login:

curl -X POST https://api.playsuper.club/player/login/federatedByStudio \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "uuid": "your-unique-player-id"
  }'

Response 200 (returned without the envelope):

{
  "message": "Login successful",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Returns 404 if no player exists for that UUID, which is why Step 1 comes first. Send the token as Authorization: Bearer <token> on later requests. It stays valid across sessions until it expires; cache it rather than logging in on every launch.

Step 3: Distribute coins

Award coins after the player completes an action in your app. Replace YOUR_COIN_ID with the coin ID from the console:

curl -X POST https://api.playsuper.club/coins/YOUR_COIN_ID/distribute \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-game-uuid: your-unique-player-id" \
  -d '{
    "amount": 100
  }'

With Bearer auth, replace the x-game-uuid header with Authorization: Bearer <token>.

Response 201:

{
  "message": "Coin distribution initiated",
  "transactionId": "txn-1a2b3c4d-5678-90ab-cdef-1234567890ab"
}

An invalid or missing API key returns 401 Unauthorized. Each successful call produces a COINS_CREDITED webhook with reason: GAME_CREDIT.

Step 4: Deduct coins

Remove coins from a player's PlaySuper balance, for example when your game spends them on something you fulfil yourself, or to mirror a balance you hold elsewhere:

curl -X POST https://api.playsuper.club/coins/YOUR_COIN_ID/deduct \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-game-uuid: your-unique-player-id" \
  -d '{
    "amount": 40
  }'

Response 201:

{
  "message": "Coin deduction initiated",
  "transactionId": "txn-9f8e7d6c-5432-10ab-cdef-1234567890ab"
}

Each successful call produces a COINS_DEBITED webhook with reason: GAME_DEBIT. If your server both calls this endpoint and consumes webhooks, filter GAME_CREDIT and GAME_DEBIT out (or set excludedReasons on the webhook) so you do not process your own calls twice. Store purchases arrive as PURCHASE_DEBIT and are debited by PlaySuper; you do not call deduct for them.

Step 5: List and filter rewards

Fetch the rewards available for purchase. coinId is required. Pass x-language for translated content (see Language support):

curl "https://api.playsuper.club/rewards?coinId=YOUR_COIN_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-language: en"

Response 200, a paginated object (one item shown, fields truncated; see the Swagger docs for the full schema):

{
  "data": [
    {
      "id": "reward-abc-123",
      "name": "₹500 Gift Card",
      "description": "Redeemable online and in-store",
      "type": "GIFT_CARD",
      "brandId": "brand-001",
      "brandName": "Starbucks",
      "endDate": "2026-12-31T23:59:59.000Z",
      "availableQuantity": 250,
      "price": 500,
      "metadata": {
        "brandName": "Starbucks",
        "brandLogoImage": "https://assets.playsuper.club/brands/starbucks.png",
        "campaignCoverImage": "https://assets.playsuper.club/campaigns/starbucks-500.png",
        "brandCategory": ["Food"],
        "campaignTitle": "Starbucks ₹500 Gift Card",
        "campaignSubTitle": "Valid at all outlets in India",
        "campaignDetails": "...",
        "termsAndConditions": "...",
        "howToRedeem": "..."
      }
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Omitting coinId returns 400 with "Coin ID is required".

Filter parameters

Example requests

# Filter by category
GET /rewards?coinId=coin-123&category=Food

# Paginated brand-specific rewards
GET /rewards?coinId=coin-123&brand=Starbucks&limit=20&page=1

# Look up specific rewards (repeat rewardIds once per ID)
GET /rewards?coinId=coin-123&rewardIds=reward-abc-123&rewardIds=reward-def-456

# Gift cards only, one per brand
GET /rewards?coinId=coin-123&dedupeBrandsByDiscount=true

All requests require x-api-key. x-language is optional.

Step 6: Purchase a reward

Let a player spend coins on a reward:

curl -X POST https://api.playsuper.club/rewards/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-game-uuid: your-unique-player-id" \
  -d '{
    "rewardId": "reward-abc-123",
    "coinId": "YOUR_COIN_ID"
  }'

With Bearer auth, replace the x-game-uuid header with Authorization: Bearer <token>. Pass an x-idempotency-key header to retry safely without double-purchasing.

About isPrefillEnabled. By default the purchase debits the reward's price from the player's PlaySuper wallet, and fails if the balance is too low. With isPrefillEnabled: true, PlaySuper first credits the player exactly the reward's price and then debits it, so the purchase always goes through and the wallet ends where it started. Both entries appear in the transaction history and as GAME_CREDIT and PURCHASE_DEBIT webhooks.

Set it to true when your game keeps the coin balance and you have already checked and deducted the price on your side, so PlaySuper is only fulfilling the reward. Leave it false when players earn coins through /distribute and spend from their PlaySuper wallet.

Response 201:

{
  "orderId": "order-789",
  "orderType": "COUPON",
  "status": "COMPLETED",
  "totalAmount": 500,
  "createdAt": "2026-07-13T10:30:00.000Z",
  "couponCode": "SB500-XXXX-YYYY",
  "pin": "1234",
  "campaignName": "Starbucks ₹500 Gift Card",
  "transactionId": "txn-456",
  "rewardId": "reward-abc-123",
  "metadata": {
    "brandName": "Starbucks",
    "brandLogoImage": "https://assets.playsuper.club/brands/starbucks.png",
    "howToRedeem": "...",
    "termsAndConditions": "...",
    "couponExpiryDateExists": true,
    "couponExpiryDate": "2026-12-31T23:59:59.000Z"
  }
}

pin is null when the reward has no PIN.

Response 400 (for example, requesting a new code too soon):

{
  "message": "Code already requested for this offer, please wait some time before requesting a new code",
  "statusCode": 400
}

Player management endpoints

Get player profile

Requires a Bearer token (this endpoint does not accept x-game-uuid):

curl https://api.playsuper.club/player/profile \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Returns the player object (ID, phone, name and linked identifiers).

View coin balances

Accepts either x-game-uuid or a Bearer token:

curl https://api.playsuper.club/player/funds \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-game-uuid: your-unique-player-id"

Response 200, an array as the data payload:

[
  {
    "id": "wallet-123",
    "playerId": "d2f1a3b4-5678-90ab-cdef-1234567890ab",
    "coinId": "YOUR_COIN_ID",
    "balance": 1500,
    "coin": {
      "name": "Gold Coin",
      "convertionRate": 1,
      "pictureUrl": "https://assets.playsuper.club/coins/gold.png",
      "neverExpire": true,
      "isOrgWide": false
    }
  }
]

Fetch order history

Accepts either x-game-uuid or a Bearer token. The x-language header is required. page (default 1) and limit (default 10) are optional:

curl "https://api.playsuper.club/player/orders?page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-language: en" \
  -H "x-game-uuid: your-unique-player-id"

Response 200, a paginated object:

{
  "data": [
    {
      "id": "order-789",
      "orderType": "COUPON",
      "status": "COMPLETED",
      "totalAmount": 500,
      "createdAt": "2026-07-13T10:30:00.000Z",
      "couponCode": "SB500-XXXX-YYYY",
      "pin": "1234",
      "campaignName": "Starbucks ₹500 Gift Card",
      "transactionId": "txn-456",
      "rewardId": "reward-abc-123",
      "metadata": {
        "brandName": "Starbucks",
        "howToRedeem": "...",
        "termsAndConditions": "..."
      }
    }
  ],
  "metadata": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "totalPages": 2
  }
}

Language support

Add the x-language header to any request that returns user-facing content (rewards, orders, transactions). Supported codes:

GET /player/orders
x-language: fr
x-api-key: <your-api-key>
Authorization: Bearer <token>

Security best practices

Next steps

Need help?

• Swagger Docs: api.playsuper.club/docs
• Swagger JSON: api.playsuper.club/docs-json
• Technical Support: engineering@playsuper.club