PlaySuper Rewards API Quick Start Guide

📋 Overview

The PlaySuper API allows you to integrate a complete rewards system into your application. Users can earn coins through in-app activities and redeem them for real rewards including gift cards, discount coupons, and physical products.

🔑 Prerequisites

• Game API Key (obtained from PlaySuper console)
• Basic understanding of REST APIs
• Ability to make HTTP requests in your game code

🔧 Setup & Authentication

1. Obtain API Key

• Log into the PlaySuper console
• Navigate to API section
• Copy your Game API Key
• Go to https://api.playsuper.club/docs/ for full swagger documentation

2. Player Authentication

Use these endpoints to authenticate players:

Request OTP

POST /player/request-otp

Verify OTP and get access token

POST /player/login

📝 Important Note About Player Identification

PlaySuper supports two ways to identify players:

1. Phone Number + OTP (shown above)
2. Game UUID: Use your game's internal player ID via x-game-uuid header

• You can use either method consistently throughout the API calls
• If using Game UUID:
  • Include x-game-uuid header in your requests
  • The value should be your game's unique player identifier
  • No phone authentication needed
  • Directly jump to Rewards and Distribute coin API

🌐 Web Store Embedding

Obtain Authentication Token

First, create a player using the UUID and obtain a JWT token through the federated login endpoint:

POST /player/login/federatedByStudio
Headers:
  x-api-key: YOUR_API_KEY
Body:
  { "uuid": "YOUR_PLAYER_ID" }

Embed the Store with PostMessage Communication

Once you have the token, create an iframe and use postMessage for secure communication:

// After obtaining the token from loginWithUuid endpoint
const token = response.data.access_token;
const apiKey = 'YOUR_API_KEY';

// Create and configure iframe for the PlaySuper store
const iframe = document.createElement('iframe');

// Add API key as URL parameter
const storeUrl = new URL('https://store.playsuper.club');
storeUrl.searchParams.set('apiKey', apiKey);
iframe.src = storeUrl.toString();

// Configure iframe security settings
iframe.setAttribute('sandbox', 'allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-storage-access-by-user-activation');
iframe.setAttribute('allow', 'cross-origin-isolated');

// Set up message listener for store communication
window.addEventListener('message', (event) => {
    try {
        const response = event.data;

        if (response.type === 'STORE_READY') {
            // Store is ready to receive the auth token
            sendAuthToken();
        }
    } catch (error) {
        console.error('Error processing store message:', error);
    }
});

// Function to send auth token to store
function sendAuthToken() {
    const authMessage = {
        type: 'SET_AUTH_TOKEN',
        value: token
    };

    iframe.contentWindow.postMessage(authMessage, '*');
}

// Add iframe to DOM
document.body.appendChild(iframe);

Communication Flow

The communication between your application and the PlaySuper store follows this pattern:

1. Store Initialization: The iframe loads with the API key as a URL parameter
2. Ready Signal: The store sends a STORE_READY message when it's ready to receive authentication
3. Token Delivery: Your application responds by sending the auth token via SET_AUTH_TOKEN message
4. Store Activation: The store uses the provided token for authentication

Important Implementation Details

• API Key: Must be provided as a URL parameter when loading the iframe
• Authentication Token: Sent via postMessage after receiving the STORE_READY signal
• Security: Use appropriate iframe sandbox attributes for security
• Communication: All data exchange happens through postMessage, not localStorage
• Error Handling: Implement proper error handling for message communication

Message Types

Incoming Messages (from store):

• STORE_READY: Indicates the store is ready to receive authentication

Outgoing Messages (to store):

• SET_AUTH_TOKEN: Provides the JWT token for player authentication

{
    type: 'SET_AUTH_TOKEN',
    value: 'your-jwt-token-here' // (without Bearer prefix)
}

💰 Managing Coins

Distribute Coins

Reward players with coins:

POST /coins/{coinId}/distribute

Replace {coinId} with the appropriate coin identifier.

🎁 Handling Rewards

1. Fetch Available Rewards

Get list of rewards players can purchase:

GET /rewards

🔍 Filtering Rewards

The /rewards endpoint supports powerful filtering options to help you customize the rewards experience:

GET /rewards

Available Filter Parameters

Example Requests

Basic category filtering:

GET /rewards?coinId=coin-123&category=Food
Headers:
  x-language: en
  x-api-key: <your-api-key>

Paginated brand-specific rewards:

GET /rewards?coinId=coin-123&brand=Starbucks&limit=20&page=1
Headers:
  x-language: en
  x-api-key: <your-api-key>

Looking up specific rewards:

GET /rewards?coinId=coin-123&rewardIds=["reward-abc-123","reward-def-456"]
Headers:
  x-language: en
  x-api-key: <your-api-key>

Gift Card Filter:

GET /rewards?coinId=coin-123&giftCard=true
Headers:
  x-language: en
  x-api-key: <your-api-key>

2. Purchase Reward

Allow players to buy rewards:

Use either Bearer token OR x-game-uuid header for authentication:

POST /rewards/purchase
Headers:
  Authorization: Bearer <token>
  // OR
  x-game-uuid: <your-game-player-id>

Note: isPrefillEnabled Parameter

The isPrefillEnabled parameter in the /rewards/purchase endpoint is a boolean value that controls the automatic handling of coin transactions during reward redemption:

• When set to true: The system automatically distributes the same amount of coins to the player and then immediately deducts them when redeeming the reward. This maintains consistency in the transaction system by creating both credit and debit entries.
• By default, this works with isPrefillEnabled set to false.

Example usage in request body:

{
  "rewardId": "reward-123",
  "coinId": "coin-456", 
  "isPrefillEnabled": true
}

👤 Player Management

All player endpoints support both authentication methods - Bearer token OR x-game-uuid header:

Create Player using UUID

Create player profile using your game's unique-identifier:

POST /player/create-with-uuid
Headers:
  x-game-uuid: <your-game-player-id>

Get Player Profile

Retrieve player information:

GET /player/profile
Headers:
  Authorization: Bearer <token>
  // OR
  x-game-uuid: <your-game-player-id>

View Player Wallets

Check player's coin balances:

GET /player/wallets
Headers:
  Authorization: Bearer <token>
  // OR
  x-game-uuid: <your-game-player-id>

Fetch Player Orders

Get history of reward purchases:

GET /player/orders
Headers:
  Authorization: Bearer <token>
  // OR
  x-game-uuid: <your-game-player-id>

🌐 Language Support

For fetching orders, rewards, and transactions, you can specify the desired language using the x-language header with the appropriate language code. The following languages are supported:

To use a specific language, include the x-language header in your API requests. For example:

GET /player/orders
Headers:
  x-language: fr
  Authorization: Bearer <token>
  // OR
  x-game-uuid: <your-game-player-id>

This will return the order information in French.

🔒 Important Security Notes

📚 Next Steps

• Explore full API documentation at https://api.playsuper.club/docs/
• Implement error handling and edge cases
• Test thoroughly in a staging environment before going live

🆘 Need Help?

• Full API Documentation: api.playsuper.club/docs
• Swagger JSON: api.playsuper.club/docs-json
• Technical Support: engineering@playsuper.club
• Schedule Demo: aishikpyne@playsuper.club

Happy integrating! 🎮✨