# Create Bonus

Gives a user one bonus round on a slot game: a winning round worth up to `amount`, played at a stake of at most `max_bet`.

The user does not have to be playing when you create it. The bonus waits until the user's next round on that game at a total bet of `max_bet` or less. That round is then one whose win at the user's stake is at most `amount` and at least 70% of it. The user pays the round's bet as usual and gets its win like any other win.

A user can hold several bonuses on the same game. They are given one after the other, in the order they were created.

> **`PRAGMATIC` only for now.** Bonuses are supported on Pragmatic games and nowhere else yet. Sending `bonus_create` for any other `provider_code` fails with code `7770407`. More providers are planned.

### Endpoint

```
POST https://api.nexusggr.com
```

**Content-Type:** `application/json`

### Request

**Method:** `bonus_create`

```json
{
    "method": "bonus_create",
    "agent_code": "your_agent_code",
    "agent_token": "your_agent_token",
    "user_code": "test",
    "provider_code": "PRAGMATIC",
    "game_code": "vs20doghouse",
    "bonus_id": "bonus_777",
    "max_bet": 2000,
    "amount": 50000
}
```

| Field           | Type    | Required | Description                                                                                          |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `method`        | string  | Yes      | Must be `bonus_create`                                                                               |
| `agent_code`    | string  | Yes      | Your agent code                                                                                      |
| `agent_token`   | string  | Yes      | Your agent API token                                                                                 |
| `user_code`     | string  | Yes      | Target user                                                                                          |
| `provider_code` | string  | Yes      | Game provider code. `PRAGMATIC` for now                                                              |
| `game_code`     | string  | Yes      | Game identifier                                                                                      |
| `bonus_id`      | string  | Yes      | Your own identifier for the bonus, 1 – 36 characters, unique for your agent. It comes back in the callbacks and is used to cancel the bonus |
| `max_bet`       | integer | Yes      | Highest total bet per spin, in your currency, at which the bonus round is given. At least `1`        |
| `amount`        | number  | Yes      | The most the bonus round pays, in your currency: more than `0`, with at most 2 decimals              |

> **When the bonus is given.**
>
> - Only a normal round can carry the bonus: a round with a total bet above `max_bet`, or with an ante bet, does not.
> - If the game has no round whose win at the user's stake lies between 70% and 100% of `amount`, the bonus keeps waiting for a round at another stake.
> - The round's win can be a few wins in a row (for example its free spins). The bonus ends when that round is over.

### Response

#### Success

```json
{
    "status": 1,
    "code": 7777777,
    "msg": "SUCCESS",
    "bonus_id": "bonus_777",
    "user_code": "test",
    "provider_code": "PRAGMATIC",
    "game_code": "vs20doghouse",
    "max_bet": 2000,
    "amount": 50000
}
```

**Balance:** `amount` is deducted from your agent balance the moment the bonus is created. When the bonus round ends, what it did not pay (`amount` minus its win) comes back to your agent balance. If you cancel the bonus, what it has not paid comes back then (see [Cancel Bonus](https://my.nexusggr.com/app/docs/integration/bonus-api/cancel-bonus)). A bonus is refunded only once.

**Callbacks:** in Seamless mode, the `transaction` callbacks of the bonus round also carry `bonus_id`, `bonus_total_win` and `bonus_end` inside `slot`. See [Transaction (Site Endpoint)](https://my.nexusggr.com/app/docs/integration/seamless-api/transaction-site-endpoint).

#### Failure

```json
{
    "status": 0,
    "code": 7770026,
    "msg": "Duplicated Bonus Id."
}
```

```json
{
    "status": 0,
    "code": 7770502,
    "msg": "External Error : INVALID_GAME"
}
```

| Code      | Description                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------- |
| `7770003` | The user does not exist                                                                             |
| `7770014` | Your agent balance does not cover `amount`. `msg` adds both, for example `Insufficient agent funds. (bonus: 50000, agent balance: 30000)` |
| `7770026` | The `bonus_id` was already used by your agent, including by a bonus that was refused or canceled     |
| `7770407` | The provider does not exist, is disabled, or does not support bonuses                              |
| `7770500` | Internal error. The bonus may still have been created: see **No answer** below                     |
| `7770502` | The game server refused the bonus. The text after `External Error : ` says why (table below)        |

| Reason             | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `INVALID_GAME`     | The game does not exist or is switched off                     |
| `INVALID_MAX_BET`  | `max_bet` is not a whole number above `0`                      |
| `INVALID_AMOUNT`   | `amount` is not above `0`                                      |
| `INVALID_DATA`     | A code or `bonus_id` is empty or not valid text                |
| `DUPLICATED_BONUS` | The game server already knows this `bonus_id`                  |
| `PLAYER_BUSY`      | The user's game was busy with a request. Try again             |

A refused bonus gives all of `amount` back to your agent balance at once. Its `bonus_id` stays used, so send a new one when you try again.

**No answer from the game server:** the answer is then `External Error : the request to the PRAGMATIC game server failed` (or `7770500`), but the bonus may still have been created there. It is canceled at once when possible, and `amount` comes back. If that is not possible, `amount` stays deducted until the bonus is played or you send **Cancel Bonus** with the same `user_code`, `game_code` and `bonus_id`, which settles it.

An invalid `amount` (`0` or less, or more than 2 decimals) is refused before the game server is asked: code `7770006`, with the reason in `msg` (see [Response Codes](https://my.nexusggr.com/app/docs/integration/response-codes)).