Promotions & Activities

Overview

• Description: Fetch the list of available promotions for the current player, and provide promotion details and application endpoints.

Business Logic & Explanations

WARNING

Promotions are not purely for display; they are deeply tied to the player's wallet turnover and anti-fraud mechanics. When translating this to a pure API, the following rules MUST be implemented:

1. Encrypted Parameter Transmission: When returning the list of eligible promotions, the system does NOT return the plain-text promo_id. Instead, it returns a Sha256 encrypted Token (e.g., sha256('deposit' + id)). The client must submit this encrypted Token when applying for a promo, which prevents scripts from traversing and abusing IDs.
2. Multi-Dimensional Fraud Prevention (Restriction Types 1-5):
   • Type 1 & 2: Limited to once per day.
   • Type 3: Limited to once per week.
   • Type 4: Limited to once per month.
   • Type 5: Valid only on specific days configured in the backend (e.g., Tuesdays only).
3. Group Restrictions (Mutual Exclusivity): If multiple promotions are configured with the same group_id, the fraud-prevention restrictions mentioned above will apply to the entire Group. For example, if a player claims Promo A in the group today, they cannot claim Promo B in the same group today.
4. Auto Assign (Seamless Dispatch): If a promotion has promo_autoassign = 1, the player does NOT need to manually call the claim endpoint. The system will automatically credit the bonus when the player completes Registration (promo_deposit_type = 1) or a Regular Deposit (promo_deposit_type != 1) and meets the required VIP level.
5. Turnover Binding: Upon claiming a promotion, the backend calculates the required turnover and adds it to the wallet's sum_winover. All withdrawal requests will be blocked until this required turnover is fully met.

---

1. GET - Fetch Promotion List

• Path: /api/promotions/list

Request Headers

Parameter	Type	Required	Description
Authorization	String	No	Bearer Token (If unauthenticated, only public promos are returned without user-specific filtering)

Response Example

{
  "code": 0,
  "msg": "Success",
  "data": [
    {
      "title": "Welcome Bonus 100%",
      "promo_token": "a1b2c3d4e5f6g7h8i9j0...", // Encrypted Token for claiming
      "min_topup": 50.00,
      "max_topup": 1000.00,
      "banner_url": "https://api.domain.com/images/banner1.webp",
      "auto_assign": false
    }
  ]
}

2. GET - Fetch Promotion Details

• Path: /api/promotions/detail

Request Parameters

Parameter	Type	Required	Description
promo_token	String	Yes	Encrypted Token from the promo list

Response Example

{
  "code": 0,
  "msg": "Success",
  "data": {
    "title": "Welcome Bonus 100%",
    "description": "<p>Here is the html detail of the promo...</p>",
    "end_date": "2026-12-31 23:59:59"
  }
}

3. POST - Claim Promotion

NOTE

Usually, promotions are claimed alongside a deposit by passing the promo_token during the deposit submission. This standalone endpoint is only used if a promotion requires no deposit (e.g., free credits).

• Path: /api/promotions/claim

Request Parameters

Parameter	Type	Required	Description
promo_token	String	Yes	Encrypted Token from the promo list

Response Example

{
  "code": 0,
  "msg": "Promotion claimed successfully",
  "data": {
    "bonus_amt": 50.00,
    "turnover_required": 1000.00
  }
}