Free rounds you issue
POST /v2/aggregator/issue_grant
| Field | Required | Meaning |
|---|---|---|
player_ref, game_ids[] | yes | Who and on which games. |
rounds_total | yes | Number of free rounds. |
round_value | yes | Stake value of one round (Money). |
bet_level, lines | no | Provider bet level and lines, from get_bet_ranges (§6.1) where the game has levels. |
settlement_mode | no | GA supports only SETTLEMENT_MODE_ON_COMPLETION. Leave it out. |
idempotency_key | recommended | The same key returns the same grant. GA refuses a different body under the same key with IDEMPOTENCY_CONFLICT. Without a key every call creates a new grant. |
valid_until | yes | Hard end date. GA refuses rounds after it. |
external_ref | no | Your campaign or bonus id. |
Response: Grant with grant_id, status (active, exhausted, expired, cancelled, settled), rounds_remaining, rounds_played, accumulated_win.
How the money flows for a grant you issued: no bet and no win reaches your wallet while the player plays the rounds. The win accumulates on the grant. When the grant is exhausted, expired, or cancelled with a win, GA sends one settle_grant to your wallet with total_win, and that’s when you credit the player (§5.9). GA also settles a zero-win grant, with total_win: 0.
list_grants (by player_ref and status) and cancel_grant (grant_id, reason) complete the set. You can cancel only an active grant, and GA still settles the win already earned.
Reference
- POST
/v2/wallet/settle_grant— Settle free-round grant: parameters, errors, code samples, try it - POST
/v2/aggregator/issue_grant— issueGrant: parameters, errors, code samples, try it - POST
/v2/aggregator/grants— listGrants: parameters, errors, code samples, try it - POST
/v2/aggregator/cancel_grant— cancelGrant: parameters, errors, code samples, try it