Skip to content

Gift API (Free Bets)

The Gift API allows Operators to grant free bets (gifts) to players directly on the Game Provider platform.

Unlike the Wallet API (where Game Provider calls you), this API is Inbound (you call Game Provider).

  • Base URL: https://api.game-provider.com/api/v1/game-gifts (Production)
  • Method: POST
  • Security: Requires X-Public-Key and X-Signature (HMAC SHA256 of the body).

1. Grant Gifts

Award one or more free bets to a player.

  • Endpoint: /api/v1/game-gifts

Request Payload

{
  "portalName": "MyCasino",
  "client": {
    "operatorTxId": "gift-tx-001",
    "userId": "player123",
    "currencyCode": "USD"
  },
  "gifts": [
    {
      "gameName": "chicken-race",
      "giftKey": "promo-welcome-bonus",
      "quantity": 10,
      "betLevel": 100,
      "activationDate": "2023-12-01T00:00:00",
      "expirationDate": "2023-12-31T23:59:59"
    }
  ]
}
Field Description
betLevel The value of the free bet in millis (e.g., 100 = 0.10 USD).
quantity Number of rounds gifted.
giftKey Your unique ID for this specific gift instance.

Response

{
  "code": 200,
  "message": "Success",
  "data": { ... }
}

2. Cancel Gifts

Cancel previously granted gifts.

  • Endpoint: /api/v1/game-gifts/cancel
  • Method: POST

Request Payload

{
  "portalName": "MyCasino",
  "client": {
    "operatorTxId": "cancel-tx-999",
    "userId": "player123",
    "currencyCode": "USD"
  },
  "gifts": [
    {
       "giftKey": "promo-welcome-bonus"
    }
  ]
}

Note: The structure requires the gifts list to identify which keys to cancel.

Impact on Wallet API

When a player plays a round using a Free Bet: 1. Reflect in Wallet: We definitely send a BET transaction with action: "FREE_BET" so you can track activity, but the amount deducted from the user's real balance should be 0. 2. Transactions: You will see specific action types in the Wallet API calls (e.g., FREE_BET, FREE_BET_WIN).