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