Redeem/Referral Codes

LiveOps tool to create codes with instant rewards and/or referral system with subsequent financial tracking of commissions and payouts.

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

      NameTypeRequiredDescription
      creator_idStringYesInfluencer ID in game
      redemption_codeStringYesMain 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. NameTypeRequiredDescription
        creator_idStringYesInfluencer ID in game
        pageNumberNoPage number
        page_sizeNumberNoNumber 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

      NameTypeRequiredDescription
      code_idNumberYesCode 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

      NameTypeRequiredDescription
      user_idStringYesPlayer ID who's trying to redeem the code in game
      codeStringYesCode that the player is gonna redeem
  5. Transaction Data events endpoint

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

    2. Method
      POST

    3. Request Body

      NameTypeRequiredDescription
      idStringNoUnique identifier this request
      eventsArray of ObjectsYesArray of transaction data events
    4. Transaction data events example

      [{
      	"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

      NameTypeRequiredDescription
      creator_idStringYesUnique 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

      NameTypeRequiredDescription
      campaign_idNumberYesCampaign ID
      codeStringYesRedemption code that created by creator
      code_typeStringYesRedemption code type, which should be either redeem or referral
      number_of_claimsNumberYesNumber of claims of the code
      total_revenueNumberYesTotal revenue generated by the users who claimed that code
      commission_tierNumberYesCurrent commission tier for the creator
      expected_payoutNumberYesExpected 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.

NameTypeRequiredDescription
X-API-KeyStringYesAPI Key

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