This document describes the specification of the seamless wallet API for the integration of MegaRGS content into the operator's platform.
Seamless wallet API
The specification is divided into two parts:
- Description of the endpoints on content provider side. They should be called by the operators platform to access the content.
- Description of the callback url on operators platform side. This endpoint should be implemented to enable content provider to access user's wallets.
Terminology
| Term | Definition |
|---|---|
| Content Provider | MegaRGS is the provider of the gaming content |
| Operator Platform | Gaming platform with a user management system and a wallet system, where the gaming content should be integrated into |
| Player | Casino player, user |
| Game | Single piece of content (slot game, casino table, virtual sport) |
| Session | Single gameplay of a user |
| Action | Single operation in the communication process between content provider platform and operators platform |
| Transaction | Makes a change of users balance |
Endpoints on MegaRGS side
Operator's platform should call these endpoints to get access to the gaming content.
List of available games - available_games
This endpoint will respond with a list of all available and activated games for the operator.
Endpoint URL
GET request
https://www.megargs.com/v1/?action=available_games&operator_id=youroperatorid&hash=hashwithsecret
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | available_games |
| operator_id | STRING 32 | Y | Identifier of the operator's platform |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
vertical can be one of the following values: slot, live-casino, virtual-sport, racing, poker
{
"status": 200,
"response": [{
"id": "345",
"name": "Game name",
"brand": "MegaRGS",
"vertical": "slot",
"demo_available": true,
"media": {
"icon": "https://<GAME_ICON_URL>"
}
}]
}Get real play game url - real_play
This endpoint should be called to get the url for starting a new game on the operator's platform.
Endpoint URL
GET request
https://www.megargs.com/v1/?action=real_play&player_id=playerid&game_id=gameid¤cy=currency&operator_id=youroperatorid&hash=hashwithsecret
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | real_play |
| operator_id | STRING 32 | Y | Identifier of the operator's platform |
| account_id | STRING 32 | Y | Identifier of the account of the platform |
| game_id | STRING 32 | Y | Unique game id received from action available_games |
| player_id | STRING 32 | Y | Unique player id which is used on operator's platform by the user |
| currency | STRING 3 | Y | Player’s currency. ISO 4217 format. |
| return_url | STRING 256 | N | Url encoded value of return url, if set back button will be displayed in side game which will redirect to this url |
| deposit_url | STRING 256 | N | Url encoded value of deposit url, if set deposit button will be displayed in side game menu |
| username | STRING 100 | N | Player's username |
| first_name | STRING 100 | N | First name |
| last_name | STRING 100 | N | Last name |
| skin_id | STRING 32 | N | Skin id identifying it on operators side, for which this game is launched |
| display_currency | STRING 32 | N | Player’s currency value to be displayed in game (Eur, Euro, €) |
| language | STRING 2 | N | Two letter code for the language (en, fr, lt). |
| device_type | STRING 32 | N | On which type of device the game should be opened? Possible values: mobile, desktop, cashier |
| extra | STRING 256 | N | Extra url encoded parameters and values which should be passed back with API actions, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
{
"status": 200,
"response": {
"game_url": "https://<URL>/?token=abcd1234",
"token": "abcd1234"
}
}Get demo (fun) play game url - demo_play
This endpoint should be called to retrieve the url for starting a new game in the demo mode. Be aware that not all games support the demo mode.
Endpoint URL
GET request
https://www.megargs.com/v1/?action=demo_play&player_id=playerid&game_id=gameid¤cy=currency&operator_id=youroperatorid&hash=hashwithsecret
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | real_play |
| operator_id | STRING 32 | Y | Identifier of the operator's platform |
| account_id | STRING 32 | Y | Identifier of the account of the platform |
| game_id | STRING 32 | Y | Unique game id received from action available_games |
| player_id | STRING 32 | Y | Unique player id which is used on operator's platform by the user |
| currency | STRING 3 | Y | Player’s currency. ISO 4217 format. |
| return_url | STRING 256 | N | Url encoded value of return url, if set back button will be displayed in side game which will redirect to this url |
| deposit_url | STRING 256 | N | Url encoded value of deposit url, if set deposit button will be displayed in side game menu |
| username | STRING 100 | N | Player's username |
| skin_id | STRING 32 | N | Skin id identifying it on GAP side, for which this game is launched |
| display_currency | STRING 32 | N | Player’s currency value to be displayed in game (Eur, Euro, €) |
| language | STRING 2 | N | Two letter code for the language (en, fr, lt). |
| device_type | STRING 32 | N | On which type of device the game should be opened? Possible values: mobile, desktop, cashier |
| extra | STRING 256 | N | Extra url encoded parameters and values which should be passed back with API actions, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
{
"status": 200,
"response": {
"game_url": "https://<URL>/?token=abcd1234",
"token": "abcd1234"
}
}Get bet details - bet_details
This endpoint should be called to retrieve the current status for a specific bet.
Endpoint URL
https://www.megargs.com/v1/?action=bet_details&operator_id=youroperatorid&bet_id=betid&hash=hashwithsecret
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | bet_details |
| operator_id | STRING 32 | Y | Identifier of the operator platform |
| bet_id | STRING 32 | Y | Unique bet id received from the make bet action |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
{
"status": 200,
"response": {
"transaction_id": "123123123123",
"bet_status": "won",
}
}Endpoint on operator side
Operator platform should implement the following endpoint to enable content provider to access player's wallets. The url of this endpoint (the callback url) should be communicated to the content provider.
Get player balance - balance
This action will be called to request the current player's balance.
POST request to the callback url. The parameters are sent via POST request body.
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | balance |
| player_id | STRING 32 | Y | Unique player id |
| currency | STRING 3 | Y | Player’s currency. ISO 4217 format. |
| vertical | STRING | N | Balance related to the requested vertical. Can have values: slot, live-casino, virtual-sport, racing, poke. |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
| extra | STRING 256 | N | Extra url encoded parameters and values which should be passed back with API actions, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
Response:
Includes the new player balance
{
"status": 200,
"balance": 20000,
"currency": "EUR"
}Make a bet - bet
This action will be called to place a new bet. Players balance should be decreased.Action amount can be zero for free-bets.During the round player can increase his stake. In this case an aditional bet call will happen with the already known bet_id.
POST request to callback url. The parameters are sent via POST request body.
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | bet |
| amount | INT 32 | Y | Stake value, in cents, for bet. Will be subtracted from player balance |
| win_amount | INT 32 | N | Win value, in cents. Will be added to player balance. Can be 0 if player lost. |
| player_id | STRING 32 | Y | Unique player id |
| game_id | STRING 32 | Y | Unique game id |
| bet_id | STRING 32 | Y | Unique bet id |
| transaction_id | STRING 128 | Y | Unique current transaction id |
| currency | STRING 3 | Y | Player’s currency. ISO 4217 format. |
| type | STRING 32 | N | Type of the bet |
| details | STRING 256 | N | Extra url encoded parameters and values, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| extra | STRING 256 | N | Extra url encoded parameters and values which where passed to game launch actions - "real_play" and "demo_play", eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
Includes the new player balance
{
"status": 200,
"balance": 20000,
"currency": "EUR"
}Settlement of a bet - settlement
This action is called to settle previously placed bet. Action amount can be zero if user's bet has lost.
Note, this action called in any case. Not matter win user or lost. In case, when user lose, amount will be zero.
POST request to callback url. The parameters are sent via POST request body.
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | settlement |
| amount | INT 32 | Y | Win value, in cents. Will be added to player balance. Can be 0 if player lost. |
| player_id | STRING 32 | Y | Unique player id |
| game_id | STRING 32 | Y | Unique game id |
| bet_id | STRING 32 | Y | Unique bet id |
| transaction_id | STRING 128 | Y | Unique current transaction id |
| currency | STRING 3 | N | Player’s currency. ISO 4217 format. |
| type | STRING 32 | N | Type of the bet |
| details | STRING 256 | N | Extra url encoded parameters and values, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| extra | STRING 256 | N | Extra url encoded parameters and values which where passed to game launch actions - "real_play" and "demo_play", eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
Includes the new player balance
{
"status": 200,
"balance": 20000,
"currency": "EUR"
}Correction of settlement - correction
This action is called to correct the settlement. Amount of correction action can be with + or - sign. If sign is positive, player balance should be increased by this amount. If sign is negative player's balance should be decreased by this amount.
Each correction action is sent with it's own unique transaction_id.
- This method will be repeated in case of network communication problems.
- Operator platform should check, if the transaction with same id is already received and processed.
POST request to callback url
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | correction |
| amount | INT 32 | Y | Value by which the balance should be changed. |
| player_id | STRING 32 | Y | Unique player id |
| game_id | STRING 32 | Y | Unique game id |
| bet_id | STRING 32 | Y | Unique bet id |
| transaction_id | STRING 128 | Y | Unique current transaction id |
| currency | STRING 3 | N | Player’s currency. ISO 4217 format. |
| type | STRING 32 | N | Type of the bet |
| details | STRING 256 | N | Extra url encoded parameters and values, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| extra | STRING 256 | N | Extra url encoded parameters and values which where passed to game launch actions - "real_play" and "demo_play", eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
Includes the new player balance
{
"status": 200,
"balance": 20000,
"currency": "EUR"
}Cancel failed bet - cancel
This action is called when a previously made bet should be canceled. Action cancel will be sent only in case if something get wrong on content provider side – broken RNG, server error.
POST request to callback url. The parameters are sent via POST request body.
Request:
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | STRING 32 | Y | cancel |
| amount | INT 32 | Y | Win value, in cents. Will be added to player balance. Can be 0 if player lost. |
| player_id | STRING 32 | Y | Unique player id |
| game_id | STRING 32 | Y | Unique game id |
| bet_id | STRING 32 | Y | Unique bet id |
| transaction_id | STRING 128 | Y | Unique current transaction id |
| currency | STRING 3 | N | Player’s currency. ISO 4217 format. |
| type | STRING 32 | N | Type of the bet |
| details | STRING 256 | N | Extra url encoded parameters and values, eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| extra | STRING 256 | N | Extra url encoded parameters and values which where passed to game launch actions - "real_play" and "demo_play", eg. for "param1=value1¶m2=value2" it will be - extra=%22param1%3dvalue1%26param2%3dvalue2%22 |
| hash | STRING 64 | Y | HMAC sha256 hash of alphabetically sorted request parameters |
Response:
Includes the new player balance
{
"status": 200,
"balance": 20000,
"currency": "EUR"
}Reconciliation of actions
- BET actions will be called once with 5 seconds timeout.
- If after 5 seconds BET failed (timeout, network error, response with unknown error, invalid response format) then CANCEL action will be sent.
- SETTLE, CORRECTION and CANCEL actions will be sent with some growth timeout till response with success is received.
Security
Any request should be signed with a security hash. The hash is calculated via HMAC sha256 hash of request parameters. Before hashing all query parameters should be sorted alphabetically and their values urlencoded.
From the operator side to MegaRGS outgoing requests should be signed with your SECRET key.
Example for the request of available games - https://www.megargs.com/v1/?action=available_games&operator_id=youroperatorid&hash=hashwithsecret where the hash is calculated from the following string action=available_games&operator_id=youroperatorid
From MegaRGS to the operator incoming requests are signed with your SALT key. These requests should be validated by checking the included signature to make sure that the request was not modified by the man in the middle attack.
Example request URL - https://<OPERATOR_URL>?action=balance&hash=19a82342dfdfg4f28fb42e82294b41b1a79309b1538ab973823d1e21b8&player_id=1¤cy=EUR
- Make payload string from request URL – remove "hash" parameter, sort parameters alphabetically by parameter name. Example payload string:
action=balance¤cy=EUR&player_id=1 - Using defined salt calculate HMAC hash with sha256 on payload string
- Compare provided hash with the calculated hash on your side. If the hash don't match, reply with error code ER02
Please note that two different secrets are used. One for the communication in the direction from operator's platform to content provider. And an other for the communication in the direction content provider to operator's platform.
Currencies
MegaRGS games can support any currency provided by casino.
Errors
The operator's system in case of an error replies with the following error message
{
"status": 500,
"error": {
"code": "ER01",
"message": "Unsupported action"
}
}Error codes
Following error codes can be used in the error response
- ER00 — Server error.
- ER01 — Unsupported action
- ER02 — Hash don't match
- ER11 — Wrong password.
- ER20 — User not found.
- ER21 — Insufficient funds.
- ER30 — Ticket not found.
- ER31 — Transaction amount mismatch.
- ER40 — Login session expired.
- ER41 — Wrong login session.
- ER42 — Bet rejected by regulative.