Redeem/Referral Codes

1. Document Overview

• Version: v 1.0
• Date: Oct 25 2024

2. High Level Structure

1. Redeem Codes on Helika Portal

   1. Create campaign

      
      1. Name - name of the campaign. Internal use.
      2. Start/End Date and Time. When the campaign is scheduled.
      3. Status.

   2. Create a Code

      
      1. Code value - the one that can be redeemed if entered in the game
      2. Code name - the one that will appear in the Helika Portal in the list of codes associated with a campaign
      3. Root URL - the one where the campaign is located. E.g. helika.io/game/redeems
      4. Code URL - final result for the redeem URL. E.g. helika.io/game/redeems?code=testcode
      5. Usage limit - how many users can redeem this code before it expires
      6. Status active (Y/N)
      7. Rewards - JSON blob that will be passed directly to your project
      8. Use as referral code (Y/N) - apply these rewards to your referral code campaign

   3. Data is saved in the Helika Backend

2. Referral Codes in the Client's App/Web page

   • An endpoint for Helika API to receive Redeem code info
   • Based on that info a referral code can be created by influencers
   • Client can optionally create a page to moderate and approve custom codes from influencers
   • After the referral code is created and approved it's sent through the API to Helika

3. Referral/Redeem Codes in the Client's Game

   • User enters the game
     • If the code is a link it's redeemed automatically on login
     • If the code has to be entered it's redeemed through entering the code on a dedicated page in the game or web page
   • The code is sent to Helika for validation
   • If validation is passed a success event is sent to the game that starts redeem award animation
   • The information about redemption event is sent to Helika for tracking purposes
     • If referral code was used the user is linked to the code creator
     • If the user is already linked to a creator this step is skipped

4. Purchases, commission and payouts

   • Each real money transaction is passed to Helika
   • Helika aggregates this information:
     • Close to real time displays the campaign results in the Helika Portal Dashboards
     • Once a day sends out information about the influencer's personal result and expected commission
     • Once a month or at the end of the campaign prepares a csv list of influencers with their respective payouts and sends it to a client to perform the payout

3. API Structure

1. API Rundown

1. Create Creator Code
   Create individual referral code for each influencers

   1. URL
      {{serverUrl}}/v1/redemption-codes/creator

   2. Method
      POST

   3. Request Body

      Name	Type	Required	Description
      creator_id	String	Yes	Influencer ID in game
      redemption_code	String	Yes	Main code that the influencer is referring

2. Fetch Creator Codes
   Get all referral codes created by specific influencer

   1. URL
      {{serverUrl}}/v1/redemption-codes/creator
   2. Method
      GET
   3. Request Query Parameter

      1. Name	Type	Required	Description
         creator_id	String	Yes	Influencer ID in game
         page	Number	No	Page number
         page_size	Number	No	Number of codes in one page

3. Fetch Creator Code Detail
   Get referral code detailed information for specific code created by influencer

   1. URL
      {{serverUrl}}/v1/redemption-codes/creator/{{code_id}}

   2. Method
      GET

   3. Request Param

      Name	Type	Required	Description
      code_id	Number	Yes	Code ID created by influencer Use the ID from the Fetched data

4. Redeem the code

   1. URL
      {{serverUrl}}/v1/redemption-codes/use/redeem

   2. Method
      POST

   3. Request Body

      Name	Type	Required	Description
      user_id	String	Yes	Player ID who's trying to redeem the code in game
      code	String	Yes	Code that the player is gonna redeem

   4. Response Data

      Name	Type	Required	Description
      rewards	Array of Objects	Yes	Redeem rewards data

5. Transaction Data events endpoint

   1. URL
      {{serverUrl}}/v1/game/game-event

   2. Method
      POST

   3. Request Body

      Name	Type	Required	Description
      id	String	No	Unique identifier this request
      events	Array of Objects	Yes	Array of transaction data events

   4. Transaction data events example

      JSON

      [{
      	"event_type": "payment",
      	"created_at": "2024-10-30T08:29:41.417Z",
      	"game_id": "",
      	"event": {
      		"user_id": "5095fd46-ac20-4c7f-a6e8-b1406fb1d5f7",
      		"amount": 100
      	}
      }]
      

   5. Transaction data event format

      1. event_type should be payment

      2. game_id is unique identifier of your game

      3. created_at is event created datetime

      4. event should contain two fields

         1. user_id is unique identifier of the payer in the organization
         2. amount is money spent amount in transaction

6. Exposing aggregated table with a summary per creator

   1. URL
      {{serverUrl}}/v1/redemption-codes/analytics

   2. Method
      GET

   3. Request Query Parameter

      Name	Type	Required	Description
      creator_id	String	Yes	Unique user identifier in the organization If the creator_id is "0", means that you want to get the analytics of code created by LiveOps manager

   4. Response Data
      Response data is the array of below JSON data

      Name	Type	Required	Description
      campaign_id	Number	Yes	Campaign ID
      code	String	Yes	Redemption code that created by creator
      code_type	String	Yes	Redemption code type, which should be either redeem or referral
      number_of_claims	Number	Yes	Number of claims of the code
      total_revenue	Number	Yes	Total revenue generated by the users who claimed that code
      commission_tier	Number	Yes	Current commission tier for the creator
      expected_payout	Number	Yes	Expected payout to the creator Usually calculated by multiplying commission tier percentage to total revenue

2. Authentication

Authentication is based on the API Key, where you get from Helika, or can create in Helika-Portal (Account Management -> API Keys).
Please insert the following data into API Request Header.

3. Error handling

Error response status codes list

1. 400: Bad Request
   Request data is not valid one. Failed at validation step.
2. 401: Unauthorized
   Authentication is failed.
3. 404: Not found
   The data is not found on the database.
4. 409: Duplicated Error
   The data already exists in the database.

4. Server configuration

1. Staging Environment
   Server URL: https://api-stage.helika.io
2. Prod Environment
   Server URL: https://api.helika.io

4. Differences between Code type - Redeem vs Referral

1. Redeem type

Redeem type of redemption code is the code that the players can directly redeem the rewards.

Creators can not create their own referral code/link from this redeem type code.

2. Referral type

Referral type of redemption code is the code that can not be directly redeemed by the player.

Creators needs to create their own referral code/link from this referral type code.

Players can only redeem the rewards with this creator-created code.