Gamification Coins

Gamification Coins Endpoints

Warning

Testing Phase: These endpoints are currently in testing and not ready for production. API structure and responses may change.

This section provides all available endpoints for the gamification coins system - a virtual currency that players can earn and redeem for various rewards including cash bonuses, free rounds bonuses, and physical items.

Overview

The gamification coins system allows:

  • Balance Management: Track player coins balances with full transaction history
  • Redemption: Players can redeem coins for shop items (cash bonuses, free rounds, physical items)
  • Smart Filtering: Shop items are filtered based on player context (VIP level, country, balance, game availability)
  • Transaction Tracking: Complete audit trail of all coin movements

Authentication

All endpoints require player authentication via the x-auth-token header (except Get Available Shop Items which supports both authenticated and anonymous access).

Available Endpoints

  1. Get Balance - Retrieve player’s current coins balance and totals
  2. Redeem Points - Redeem coins for shop items
  3. Get Transaction History - View paginated transaction history with filters
  4. Get Available Shop Items - Browse shop items filtered by player eligibility

Subsections of Gamification Coins

Get Balance

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves the current gamification coins balance for a player. Use gateway.[msdomain]

Request (GET)

/gateway/coins/balance/{version}/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true Brand identifier
x-auth-token header string true Player authentication token (extracted from request header)

Note: The player_id is automatically extracted from the x-auth-token header by the gateway and appended to the path when forwarding to the marketing service.

Response

Status 200

{
  "status": "success",
  "data": {
    "brand_id": 1001,
    "player_id": 12345,
    "current_balance": "250.50",
    "total_received": "500.00",
    "total_redeemed": "249.50",
    "updated_at": "2025-01-09T14:30:00Z"
  },
  "message": "Successfully retrieved player balance"
}

Response Fields:

Field Type Description
brand_id int Brand identifier
player_id int Player identifier
current_balance string Current available coins balance (decimal)
total_received string Total coins received since account creation (decimal)
total_redeemed string Total coins redeemed since account creation (decimal)
updated_at string Last balance update timestamp (ISO 8601)

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get player balance"
}

Redeem Points

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method processes a coin redemption/claim for a shop item. Use gateway.[msdomain]

The endpoint validates player eligibility, deducts coins from the player’s balance, and processes the shop item (e.g., grants a bonus, creates a free rounds bonus, or registers a physical item claim).

Request (POST)

/gateway/coins/redeem/{version}/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true Brand identifier
x-auth-token header string true Player authentication token (extracted from request header)

Note: The player_id is automatically extracted from the x-auth-token header by the gateway and appended to the path when forwarding to the marketing service.

Request Body:

{
  "shop_item_id": "507f1f77bcf86cd799439011",
  "rounds": 20,
  "trigger_source": "PLAYER_SHOP",
  "trigger_details": {
    "source_page": "shop_ui",
    "campaign": "weekend_promo"
  },
  "comment": "Weekend promotion claim",
  "uuid": "unique-idempotency-key-123"
}
Field Type Required Description
shop_item_id string true MongoDB ObjectID of the shop item to redeem
rounds int false Number of rounds for FRB selection (only required for FRB items with multiple tiers)
trigger_source string false Source of the redeem (default: “MANUAL”)
trigger_details object false Additional metadata about the redemption
comment string false Optional comment for the transaction
uuid string false Optional idempotency key to prevent duplicate redemptions

Response

Status 200 - Success

{
  "status": "success",
  "data": {
    "success": true,
    "transaction_id": 123456,
    "financial_ref_id": 78910,
    "new_balance": "150.50",
    "amount": "100.00",
    "already_processed": false
  },
  "message": "Successfully claimed coins"
}

Response Fields:

Field Type Description
success boolean Whether the redemption was successful
transaction_id int64 ID of the gamification coins transaction
financial_ref_id int64 Optional - Financial reference ID (e.g., bonus ID) if shop item created one
new_balance string Player’s new coins balance after redemption (decimal)
amount string Amount of coins deducted (decimal)
already_processed boolean True if the UUID was already used (idempotent response)

Status 422 - Validation Error

{
  "status": "fail",
  "data": {
    "result": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient balance to redeem this item"
    }
  },
  "message": "Validation error while claiming coins"
}

Common Error Codes:

  • INSUFFICIENT_BALANCE - Player doesn’t have enough coins
  • ITEM_NOT_FOUND - Shop item ID doesn’t exist
  • ITEM_NOT_ELIGIBLE - Player is not eligible for this item (segmentation/eligibility filters)
  • INVALID_ROUNDS_SELECTION - Invalid rounds parameter for FRB item
  • GAME_NOT_AVAILABLE - FRB game is not available for the player

Status 500 - Server Error

{
  "status": "error",
  "data": null,
  "message": "Failed to claim coins"
}

Example Use Cases

Redeem Cash Bonus Item

{
  "shop_item_id": "507f1f77bcf86cd799439011",
  "uuid": "unique-transaction-uuid"
}

Redeem FRB Item with Specific Rounds

{
  "shop_item_id": "507f1f77bcf86cd799439012",
  "rounds": 50,
  "uuid": "unique-transaction-uuid"
}

Redeem Physical Item

{
  "shop_item_id": "507f1f77bcf86cd799439013",
  "comment": "T-shirt size L",
  "uuid": "unique-transaction-uuid"
}

Notes

  • The endpoint automatically extracts the player’s IP address for player context validation
  • Player token from x-auth-token header is used for game availability checks (FRB filtering)
  • Idempotency: If the same uuid is provided multiple times, the first successful redemption is processed, and subsequent requests return the same response with already_processed: true
  • For FRB items with multiple rounds configurations, the rounds parameter must match one of the available tiers

Get Transaction History

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves the paginated transaction history for a player’s gamification coins. Use gateway.[msdomain]

Request (GET)

/gateway/coins/transactions/{version}/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true Brand identifier
x-auth-token header string true Player authentication token (extracted from request header)
page query int false Page number (default: 1, min: 1, max: 1000)
page_size query int false Number of items per page (default: 20, min: 1, max: 100)
transaction_type query string false Filter by transaction type (RECEIVED or REDEEMED)
start_date query string false Filter transactions from this date (ISO 8601 format)
end_date query string false Filter transactions until this date (ISO 8601 format)

Note: The player_id is automatically extracted from the x-auth-token header by the gateway and appended to the path when forwarding to the marketing service.

Query Parameter Examples:

?page=1&page_size=20
?transaction_type=REDEEMED
?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z
?page=2&page_size=50&transaction_type=RECEIVED

Response

Status 200

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "id": 123456,
        "transaction_type": "REDEEMED",
        "transaction_sub_type": "CASH_BONUS",
        "amount": "-100.00",
        "balance_before": "250.50",
        "balance_after": "150.50",
        "created_at": "2025-01-09T14:30:00Z",
        "source": "PLAYER_SHOP",
        "reference_id": 78910,
        "trigger_details": {
          "shop_item_id": "507f1f77bcf86cd799439011",
          "shop_item_name": "10 USD Cash Bonus"
        }
      },
      {
        "id": 123455,
        "transaction_type": "RECEIVED",
        "transaction_sub_type": "MANUAL",
        "amount": "50.00",
        "balance_before": "200.50",
        "balance_after": "250.50",
        "created_at": "2025-01-08T10:15:00Z",
        "source": "ADMIN_GRANT",
        "reference_id": null,
        "trigger_details": {
          "comment": "Customer satisfaction compensation"
        }
      },
      {
        "id": 123454,
        "transaction_type": "REDEEMED",
        "transaction_sub_type": "FRB",
        "amount": "-75.00",
        "balance_before": "275.50",
        "balance_after": "200.50",
        "created_at": "2025-01-07T18:45:00Z",
        "source": "PLAYER_SHOP",
        "reference_id": 54321,
        "trigger_details": {
          "shop_item_id": "507f1f77bcf86cd799439012",
          "shop_item_name": "50 Free Rounds on Starburst",
          "game_id": "starburst",
          "provider_id": "netent",
          "rounds": 50
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_pages": 5,
      "total_items": 87
    }
  },
  "message": "Successfully retrieved transaction history"
}

Response Fields:

Transaction Object:
Field Type Description
id int64 Transaction identifier
transaction_type string Type of transaction: “RECEIVED” or “REDEEMED”
transaction_sub_type string Sub-type: “MANUAL”, “CASH_BONUS”, “FRB”, “PHYSICAL”, etc.
amount string Transaction amount (decimal, negative for REDEEMED)
balance_before string Balance before the transaction (decimal)
balance_after string Balance after the transaction (decimal)
created_at string Transaction timestamp (ISO 8601)
source string Trigger source (e.g., “PLAYER_SHOP”, “ADMIN_GRANT”, “SYSTEM”)
reference_id int64 Optional - Financial reference ID (e.g., bonus ID)
trigger_details object Optional - Additional transaction metadata
Pagination Object:
Field Type Description
page int Current page number
page_size int Number of items per page
total_pages int Total number of pages
total_items int Total number of transactions

Transaction Sub-Types:

  • RECEIVED Transactions:

    • MANUAL - Manually granted coins (admin/system)

  • REDEEMED Transactions:

    • CASH_BONUS - Redeemed cash bonus item
    • FRB - Redeemed free rounds bonus item
    • PHYSICAL - Redeemed physical item

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get transaction history"
}

Notes

  • Transactions are returned in reverse chronological order (newest first)
  • Invalid query parameters (page, page_size) will be ignored and defaults will be used
  • Date filters use inclusive ranges (start_date ≤ transaction.created_at ≤ end_date)
  • The trigger_details field contains context-specific information based on the transaction type
  • For REDEEMED transactions, reference_id typically contains the financial system reference (e.g., bonus ID for CASH_BONUS)

Get Available Shop Items

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves shop items available for a specific player, filtered by player context (VIP level, country, balance, date/time) and game availability. Use gateway.[msdomain]

This endpoint is used to display the shop UI to players, showing only items they are eligible to redeem.

Request (GET)

/gateway/coins/shop/available/{version}/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true Brand identifier
x-auth-token header string false Player authentication token (optional - if not provided, returns all active items)

Note:

  • If x-auth-token is provided, the player_id is extracted and added as a query parameter (?player_id=123) when forwarding to the marketing service
  • If no token is provided, the endpoint returns all active shop items without eligibility filtering (useful for anonymous/preview mode)
  • Player IP address is automatically extracted from the request for geo-location filtering

Response

Status 200 - With Authentication

{
  "status": "success",
  "data": {
    "items": [
      {
        "item": {
          "id": "507f1f77bcf86cd799439011",
          "brand_id": 1001,
          "name": "cash_bonus_10_usd",
          "display_name": "10 USD Cash Bonus",
          "description": "Get $10 cash bonus added to your account",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "vip_level",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [3, 4, 5]
            }
          ],
          "eligibility_filters": [
            {
              "field": "balance",
              "filter_type": "numeric",
              "operator": "greater_than_or_equals",
              "comparison_val": 50.0
            }
          ],
          "type": "CASH_BONUS",
          "data": [
            {
              "currency": "USD",
              "amount": "10.00",
              "coins_cost": "100.00"
            },
            {
              "currency": "EUR",
              "amount": "8.50",
              "coins_cost": "100.00"
            }
          ],
          "purchase_stats": {
            "past_week_count": 5,
            "lifetime_count": 127
          },
          "created_at": "2024-12-01T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2025-01-05T14:30:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": true,
        "ineligible_reasons": []
      },
      {
        "item": {
          "id": "507f1f77bcf86cd799439012",
          "brand_id": 1001,
          "name": "frb_starburst_50",
          "display_name": "50 Free Rounds on Starburst",
          "description": "Get 50 free spins on Starburst slot",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "country",
              "filter_type": "string",
              "operator": "in",
              "comparison_val": ["US", "CA", "GB"]
            },
            {
              "field": "day_of_week",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [6, 7]
            }
          ],
          "eligibility_filters": [
            {
              "field": "balance",
              "filter_type": "numeric",
              "operator": "greater_than_or_equals",
              "comparison_val": 75.0
            }
          ],
          "type": "FRB",
          "data": {
            "game_id": "starburst",
            "provider_id": "netent",
            "rounds_conf": [
              {
                "rounds": 20,
                "coins_cost": "50.00",
                "duration": 30,
                "conf": [
                  {
                    "currency": "USD",
                    "wagering_multiplier": "10.00",
                    "max_winning": "100.00"
                  },
                  {
                    "currency": "EUR",
                    "wagering_multiplier": "10.00",
                    "max_winning": "85.00"
                  }
                ]
              },
              {
                "rounds": 50,
                "coins_cost": "100.00",
                "duration": 60,
                "conf": [
                  {
                    "currency": "USD",
                    "wagering_multiplier": "15.00",
                    "max_winning": "250.00"
                  }
                ]
              }
            ]
          },
          "purchase_stats": {
            "past_week_count": 12,
            "lifetime_count": 342
          },
          "created_at": "2024-11-15T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2025-01-01T12:00:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": false,
        "ineligible_reasons": [
          "balance: requires 75.00, player has 50.00",
          "day_of_week: requires [6,7], today is 3"
        ]
      },
      {
        "item": {
          "id": "507f1f77bcf86cd799439013",
          "brand_id": 1001,
          "name": "tshirt_limited_edition",
          "display_name": "Limited Edition T-Shirt",
          "description": "Get an exclusive casino branded t-shirt",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "vip_level",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [5]
            }
          ],
          "eligibility_filters": [],
          "type": "PHYSICAL",
          "data": {
            "name": "Limited Edition T-Shirt",
            "description": "Casino branded t-shirt, size L",
            "coins_cost": "500.00"
          },
          "purchase_stats": {
            "past_week_count": 2,
            "lifetime_count": 45
          },
          "created_at": "2024-10-01T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2024-12-20T16:00:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": true,
        "ineligible_reasons": []
      }
    ]
  },
  "message": "Successfully retrieved available shop items"
}

Status 200 - Without Authentication (Anonymous/Preview Mode)

{
  "status": "success",
  "data": {
    "items": [
      {
        "item": {
          "id": "507f1f77bcf86cd799439011",
          "brand_id": 1001,
          "name": "cash_bonus_10_usd",
          "display_name": "10 USD Cash Bonus",
          "description": "Get $10 cash bonus added to your account",
          "status": "active",
          "type": "CASH_BONUS",
          "data": [...],
          "purchase_stats": {
            "past_week_count": 5,
            "lifetime_count": 127
          }
        },
        "is_eligible": false,
        "ineligible_reasons": []
      }
    ]
  },
  "message": "Successfully retrieved available shop items"
}

Response Fields:

ShopItemAvailability Object:
Field Type Description
item object Shop item details (see ShopItem below)
is_eligible boolean Whether the player is eligible to redeem this item
ineligible_reasons string[] List of reasons why the player is not eligible (empty if eligible)
ShopItem Object:
Field Type Description
id string Shop item MongoDB ObjectID
brand_id int Brand identifier
name string Internal item name
display_name string User-facing display name
description string Item description
status string Item status: “active” or “inactive”
segmentation_filters Filter[] Player segmentation filters (VIP level, country, day of week, date)
eligibility_filters Filter[] Player eligibility filters (balance, etc.)
type string Item type: “CASH_BONUS”, “FRB”, or “PHYSICAL”
data object Type-specific data (see examples below)
purchase_stats object Purchase statistics (past_week_count, lifetime_count)
created_at string Creation timestamp (ISO 8601)
created_by string Creator email
updated_at string Last update timestamp (ISO 8601)
updated_by string Last updater email
Filter Object:
Field Type Description
field string Filter field: “vip_level”, “country”, “day_of_week”, “date”, “balance”
filter_type string Filter type: “numeric”, “string”, “enum”, “regex”, “date”
operator string Comparison operator: “in”, “equals”, “greater_than”, “less_than”, etc.
comparison_val any Value(s) to compare against (type depends on filter_type)
Data Types by Item Type:

CASH_BONUS:

[
  {
    "currency": "USD",
    "amount": "10.00",
    "coins_cost": "100.00"
  }
]

FRB (Free Rounds Bonus):

{
  "game_id": "starburst",
  "provider_id": "netent",
  "rounds_conf": [
    {
      "rounds": 50,
      "coins_cost": "100.00",
      "duration": 30,
      "conf": [
        {
          "currency": "USD",
          "wagering_multiplier": "15.00",
          "max_winning": "250.00"
        }
      ]
    }
  ]
}

PHYSICAL:

{
  "name": "Limited Edition T-Shirt",
  "description": "Casino branded t-shirt, size L",
  "coins_cost": "500.00"
}

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get available shop items"
}

Filtering Logic

The endpoint applies multiple layers of filtering:

  1. Status Filter: Only “active” shop items are returned
  2. Segmentation Filters (if player is authenticated):
    • VIP Level: Player’s VIP level must match filter criteria
    • Country: Player’s country (from IP) must match filter criteria
    • Day of Week: Current day must match filter criteria (1=Monday, 7=Sunday)
    • Date: Current date/time must match filter criteria
  3. Eligibility Filters (if player is authenticated):
    • Balance: Player’s coins balance must meet threshold
  4. Game Availability (for FRB items, if player is authenticated):
    • Game must be available for the player based on their token
    • Filtered rounds configurations based on player’s currency

Notes

  • Anonymous Access: If no x-auth-token is provided, all active items are returned with is_eligible: false and empty ineligible_reasons
  • Player Context: Player IP, token, VIP level, balance, and country are automatically extracted for filtering
  • FRB Filtering: For FRB items, the data.rounds_conf array is filtered to include only configurations matching the player’s currency
  • Purchase Stats: Statistics show popularity (past 7 days and lifetime)
  • Ineligible Reasons: Clear human-readable explanations for why a player cannot redeem an item
  • Multi-Currency: CASH_BONUS and FRB items can have configurations for multiple currencies