# Supplier API Overview

## **Supplier API** 

The Supplier API is designed for game developers and distributors to enable seamless integration with the Hub88 platform. By leveraging this API, gaming content can be effortlessly offered to Hub88's network of partner operators.

### Request signing logic for Supplier API

<figure><img src="https://1089485291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF8iFPgdqAwxIxP5oQMvU%2Fuploads%2FCu5FEWJIPnsBxxSNU9l0%2F%5BHub88%5D%20Documentation%20working%20board%20(6).jpg?alt=media&#x26;token=098c0754-1b59-4aad-9b3a-fa280f7d7253" alt=""><figcaption><p>Request signing in Supplier API</p></figcaption></figure>

Before the integration, the game Supplier generates a private/public key pair and sends the `public key` to Hub88. Hub88 sends its public key to the game Supplier. The body of all requests will be signed with `RSA-SHA256` using the respective `private key` and encoded to `BASE64` (We have [code examples](https://github.com/coingaming/Hub88-Examples/blob/master/README.md) in few programming languages). The signature will be placed in the `X-Hub88-Signature` header. Hub88 and the game Supplier need to verify all [**Wallet API**](https://docs.hub88.io/developer-docs/supplier-api-reference/wallet-api) requests are using the public key provided. The game Supplier verifies all [**Games API**](https://docs.hub88.io/developer-docs/supplier-api-reference/games-api) requests using the public key provided by Hub88.<br>

**Example:**

* Request body:`{"user":"3nYTOSjdlF6UTz9Ir","country":"XX","currency":"EUR","operator_id":1,"token":"cd6bd8560f3bb8f84325152101adeb45","platform":"GPL_DESKTOP","game_code":"ctl_dragonrising","lang":"en","lobby_url":"https://examplecasino.io","ip":"::ffff:10.0.0.39"}`
* Private key example for signing the example request [here](https://raw.githubusercontent.com/coingaming/Hub88-Examples/master/priv/private.pem).
* Correct signature:\
  `FFdiceKlsnmrBMhWopZYQXrJSMqxJWkynbaiOnuUE1p4mrg2UydlSAdKbOWQZ7o5USbA3SHPum3XuRCa9INWbcp+fdcOhjz0S0JLKF6uXJR2T8zlF+L+8v2lkBzPOvLg6yRuUyspxtcHB6Vlyd0Sj4v8vk5HxoVv1ZV7EpJglzHs7xKchuifjjhUwkX7AAZwvJCNKo/VZrhtfxHd/k8aq7+9h7AztiiiLO7CXbEbo8snDqMqoB/tBAImv45NcAuReBZGb3QY37MbRoOT/uQGj+9ae5VRNpJ74qs3COraDqZ5kqzsa5SjN1cML2foP13Deqp0FTY0Ek521d8CPWQY6A==`

### Request consistency

**Wallet API** requests have to be idempotent. All requests contain a `request_uuid` field. Hub88 will ensure that requests with the same `request_uuid` are not processed twice, while the response will be the same for all duplicate requests, excluding the [`/supplier/generic/v2/user/balance`](https://docs.hub88.io/developer-docs/wallet-api#post-supplier-generic-v2-user-balance) call.

***

## Gameplay overview&#x20;

***

Once you meet the prerequisites, the process on high-level as follows.&#x20;

{% stepper %}
{% step %}
**Hub88** will obtain a game URL from the game Supplier on behalf of the player and Operator.
{% endstep %}

{% step %}
**Redirect** the operator's **player** to the URL provided by the Game Supplier.
{% endstep %}

{% step %}
Respond to in-game events by forwarding wallet requests to the Operator and forwarding their responses.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**The high level gameplay corresponds to** [**the core communications flow between Supplier and Operator APIs.**](https://docs.hub88.io/developer-docs/hub88-apis/core-api-flow)
{% endhint %}

{% hint style="info" %}
Note that the process is different for **DEMO** and **REAL** gameplay modes. \
In **DEMO** mode, user can open the game, check the rules/graphics/paytable, and play with fun mode money.
{% endhint %}

### Demo gameplay

Below is an example of the interaction flow to open a game in DEMO mode:

{% stepper %}
{% step %}
**Hub88** makes a call to the **Supplier's Game API**   [`/game/url`](https://docs.hub88.io/developer-docs/games-api#post-game-url) endpoint to obtain the game launch URL. You'll know that it's a **DEMO** mode call, as Hub88 will pass `"currency":"XXX"` and parameters `token` and `user` will be omitted.
{% endstep %}

{% step %}
When the game URL is returned, the Operator uses it to direct the user to the game (for example, launch it in iframe or redirect the user to the URL).
{% endstep %}
{% endstepper %}

In **DEMO** mode, Hub88 doesn't expect any calls to [Wallet API](https://docs.hub88.io/developer-docs/supplier-api-reference/wallet-api).&#x20;

### Real gameplay&#x20;

Below is an example of the interaction flow between the User, Operator, Hub88, and the game Supplier in **REAL** mode:

{% stepper %}
{% step %}
**Hub88** generates and stores a unique game session token.
{% endstep %}

{% step %}
**Hub88** makes a call to **Supplier's Game API** [`/game/url`](https://docs.hub88.io/developer-docs/games-api#post-game-url) endpoint and passes the generated token along with the other request parameters. \
**Note:** At this point, the token is not yet active — the session is created only after a successful response is returned in step 3.
{% endstep %}

{% step %}
**Supplier** is expected to **respond** with a **valid game URL**. **The Supplier must not make any Wallet API calls (including `/user/balance`) before returning this response.** The session token becomes active only after Hub88 receives a successful `/game/url` response. \
\
When the game URL is returned, the Operator uses it to direct the user to the game, for example, launch it in an iframe or redirect the Operator to the URL.

{% hint style="warning" %}
**Do not call Wallet API endpoints before `/game/url` returns successfully.**

The session token passed in the `/game/url` request is not valid until Hub88 receives and processes a successful response. Any Wallet API call made before this point — including `/user/balance` — will be rejected with `RS_ERROR_INVALID_TOKEN`.

Wallet API calls (`/user/balance`, `/transaction/bet`, `/transaction/win`, `/transaction/rollback`) should only be made after the game URL has been returned and loaded in the player's browser (step 4 onwards).
{% endhint %}
{% endstep %}

{% step %}
When the **game URL** is loaded in the **browser**, the game **Supplier's** **server** makes a **Wallet API** call to Hub88 [`/supplier/generic/v2/user/balance`](https://docs.hub88.io/developer-docs/operator-api-reference/wallet-api#post-user-balance) endpoint.
{% endstep %}

{% step %}
**Hub88** verifies the `token` against the stored token and returns the user's balance.&#x20;

The **user** can then place a bet.
{% endstep %}

{% step %}
When the **user** attempts to place a bet, a **Wallet API** call [`/supplier/generic/v2/transaction/bet`](https://docs.hub88.io/developer-docs/wallet-api#post-supplier-generic-v2-transaction-bet) must be triggered on **Hub88 server** by the game **Supplier**.
{% endstep %}

{% step %}
**Hub88** verifies the token, forwards the request to the **Operator**, who **ensures** that the user has enough money to place this bet.

The **Operator** decreases the user's balance by the bet amount, and returns the updated user balance, which is forwarded as a response to the game **Supplier**.
{% endstep %}

{% step %}
If the **user** wins, the game **Supplier** is expected to **trigger** a [`/supplier/generic/v2/transaction/win`](https://docs.hub88.io/developer-docs/wallet-api#post-supplier-generic-v2-transaction-win) call to Hub88 server using the **Wallet API**.
{% endstep %}

{% step %}
**Hub88** verifies the token, forwards the request to the Operator.&#x20;

**Operator** must ensure an increase in the **user's balance** by the win amount and returns the updated user balance, which is forwarded as a response to the game **Supplier**.
{% endstep %}

{% step %}
Behaviour in case of **user's loss** depends on game **Supplier's** internal logic. Win can be sent with amount **`0`**.
{% endstep %}
{% endstepper %}