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
-
Redeem Codes on Helika Portal
-
Create campaign
- Name - name of the campaign. Internal use.
- Start/End Date and Time. When the campaign is scheduled.
- Status.
-
Create a Code
- Code value - the one that can be redeemed if entered in the game
- Code name - the one that will appear in the Helika Portal in the list of codes associated with a campaign
- Root URL - the one where the campaign is located. E.g. helika.io/game/redeems
- Code URL - final result for the redeem URL. E.g. helika.io/game/redeems?code=testcode
- Usage limit - how many users can redeem this code before it expires
- Status active (Y/N)
- Rewards - JSON blob that will be passed directly to your project
- Use as referral code (Y/N) - apply these rewards to your referral code campaign
-
Data is saved in the Helika Backend
-
-
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
-
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
- User enters the game
-
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
-
Create Creator Code
Create individual referral code for each influencers-
URL
{{serverUrl}}/v1/redemption-codes/creator -
Method
POST -
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
-
-
Fetch Creator Codes
Get all referral codes created by specific influencer- URL
{{serverUrl}}/v1/redemption-codes/creator - Method
GET - Request Query Parameter
-
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
-
- URL
-
Fetch Creator Code Detail
Get referral code detailed information for specific code created by influencer-
URL
{{serverUrl}}/v1/redemption-codes/creator/{{code_id}} -
Method
GET -
Request Param
Name Type Required Description code_id Number Yes Code ID created by influencer
Use the ID from the Fetched data
-
-
Redeem the code
-
URL
{{serverUrl}}/v1/redemption-codes/use/redeem -
Method
POST -
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
-
-
Transaction Data events endpoint
-
URL
{{serverUrl}}/v1/game/game-event -
Method
POST -
Request Body
Name Type Required Description id String No Unique identifier this request events Array of Objects Yes Array of transaction data events -
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 } }]
-
Transaction data event format
-
event_type
should be payment -
game_id
is unique identifier of your game -
created_at
is event created datetime -
event
should contain two fieldsuser_id
is unique identifier of the payer in the organizationamount
is money spent amount in transaction
-
-
-
Exposing aggregated table with a summary per creator
-
URL
{{serverUrl}}/v1/redemption-codes/analytics -
Method
GET -
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 -
Response Data
Response data is the array of below JSON dataName 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
orreferral
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.
Name | Type | Required | Description |
---|---|---|---|
X-API-Key | String | Yes | API Key |
3. Error handling
Error response status codes list
- 400: Bad Request
Request data is not valid one. Failed at validation step. - 401: Unauthorized
Authentication is failed. - 404: Not found
The data is not found on the database. - 409: Duplicated Error
The data already exists in the database.
4. Server configuration
- Staging Environment
Server URL: https://api-stage.helika.io - Prod Environment
Server URL: https://api.helika.io
Updated 2 days ago