Overview

The DS integration System of Game

DS API uses gRPC as protocol

Related guide: gRPC.

Game Provider applys for the information from the DS before implement it.

1. Protobuf files
2. {DS_JWT_Token} for Verify Signature Public Key
3. {access_token_here} for Authorization

• Game Provider Implement Client side from Protobuf files
• Game Provider offers a game list to DS
• Game Provider offers game launch domain, could be many, repeat and could change the weight.(the weight is bigger, the more possibility to be chosen)
• Game Provider and DS The amount in the system is multiply 10000
• The Min Bet in the system is 100

Request consistency

DS API requests have to be idempotent. All requests contain a request_uuid field.

Authentication

• DS uses API keys to allow access to the API. our will generate a DS API key, and provides the DS API key to You.
• DS expects for the API key to be included in all API requests to the server in a header that looks like the following:

METADATA:

{
    "authorization":"bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MDA3NTc0NjcsImlzcyI6InRlc3QwMSIsInBpZCI6MTA4OH0.yOMeXZCkO_bcFxhn6NmM1YBwU2lC11Vbz8oasud8Q7WGBPvcooJYiQpCPXdK8Xf8Zm_iW9bJoATAFqYXF8QnsA"
}

Authorization: bearer {access_token_here}

Related guide: gRPC Authentication.

Gameplay

DS_JWT_Token

{DS_JWT_Token} PAYLOAD:DATA:

{
  "exp": 1601304335,
  "t": "5f71f5e34be9eaba4b5cfefb",
  "demo": true
}

Support Languages

Once you meet the prerequisites, the process is as follows:

1. DS offers a game luanch url, Game Provider has to implement the url domain/login/game_id/{DS_JWT_Token}?lang={lang}
2. Game Provider auth the {DS_JWT_Token} after receiving the url, and uses the token to call member login api to get member's information.
3. Game Provider uses DS Wallet API to interact the event in the game.

DEMO

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

1. in demo mode DS will set demo = true inside the {DS_JWT_Token}, and remove the token parameter.
2. 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)
3. In DEMO mode, DS expects no wallet calls.

REAL

Sequence diagram:

Below is an example of interaction flow between the Player, Operator, DS, and game provider in REAL mode:

1. DS generates and stores a unique game session {DS_JWT_Token}.
2. DS makes a Game URL login/game_id/{DS_JWT_Token} and passes the generated {DS_JWT_Token} along with the request parameters.
3. 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).
4. When the game URL is loaded in the browser, Game Provider server makes an API Login and balance call to the DS server.
5. DS verifies the token against the stored token and returns the users balance. The user can then place a bet.
6. When the user attempts to place a bet, a Wallet API call bet is triggered on DS server.
7. Then DS verifies the token, forwards the request to the wallet API which ensures that the user has enough money to place this bet, decreases the users balance by the bet amount, and returns the updated user balance, which is forwarded as a response to the game provider.
8. If the user wins, the game provider is expected to trigger a payout call to DS server using the Wallet API.
9. DS verifies the token, forwards the request to the operator, who ensures an increase in the users balance by the win amount and returns the updated user balance, which is forwarded as a response to the game provider.
10. Behaviour in case of player's loss depends on game providers internal logic. Possible options:

• Nothing is sent
• Sent a payout with amount 0

Member

Member Structure:

message Member {

    string id = 1;
    string account = 2;

    string owner_id = 3;
    string agent_id = 5;

    string wallet_token = 6;

    // for display
    int64 balance = 7;

    string currency_code = 8;

    // Bet Limit
    int64 max_bet = 9 ;
    int64 min_bet = 10 ;
}

Member information will be returned after successful call login

Login

This endpoint login.

gRPC Request

Method:

rpc login (LoginInfoReq) returns (LoginInfoRes) {}

method api.gateway.MemberProtocolService.login

Query Parameters

Query Parameters :

message LoginInfoReq {
    string request_id = 1;
    string token = 2;
    string game_id = 3;
}

Response

Response :

message LoginInfoRes {
    string request_id = 1;
    RS status = 2; 
    Member member = 3;
}

Logout

This endpoint logout.

gRPC Request

Method:

rpc logout (LogoutInfoReq) returns (LogoutInfoRes) {}

method api.gateway.MemberProtocolService.logout

Query Parameters

Query Parameters :

message LogoutInfoReq {
    string request_id = 1;

    // When logined in successfully, use memberId and walletToken to kick out the member
    string member_id = 2;
    string wallet_token = 3;

    // When the login fails, use the login token to logout the member
    string token = 4;
}

Response

Response :

message LogoutInfoRes {
    string request_id = 1;
    RS status = 2;
}

WatchKick

• Use stream

subscribed a notification from DS that a member is kicked

gRPC Request

Method:

rpc watchKick (KickReq) returns (stream KickRes) {}

method api.gateway.MemberProtocolService.watchKick

Query Parameters

Query Parameters :

message KickReq {
}

no need any parameter

Response

Response :

message KickRes {
    string member_id = 3;
}

Wallet

Bet

This endpoint bet.

gRPC Request

Method:

rpc bet (WalletReq) returns (walletRes) {}

method api.gateway.WalletProtocolService.bet

Query Parameters

Query Parameters :

message WalletReq {
    string request_id = 1;
    string member_id = 2; 
    string game_id = 3; 
    string serial = 4;
    int64 bet_amount = 5; 
    int64 payout_amount = 6; 
    int64 valid_amount = 7; 
    int64 fee_amount = 8;
    string wallet_token = 9;
}

Response

Response :

message walletRes {
    string request_id = 1;
    RS status = 6;
    int64 balance = 7;
}

Payout

This endpoint Payout.

gRPC Request

Method:

rpc payout (WalletReq) returns (walletRes) {}

method api.gateway.WalletProtocolService.payout

Query Parameters

Query Parameters :

message WalletReq {
    string request_id = 1;
    string member_id = 2;
    string game_id = 3;
    string serial = 4;
    int64 bet_amount = 5;
    int64 payout_amount = 6;
    int64 valid_amount = 7;
    int64 fee_amount = 8;
    string wallet_token = 9;
}

Response

Response :

message walletRes {
    string request_id = 1;
    RS status = 6;
    int64 balance = 7;
}

Rollback

This endpoint Rollback.

gRPC Request

Method:

rpc rollback (WalletReq) returns (walletRes) {}

method api.gateway.WalletProtocolService.rollback

Query Parameters

Query Parameters :

message WalletReq {
    string request_id = 1;
    string member_id = 2;
    string game_id = 3;
    string serial = 4;
    int64 bet_amount = 5;
    int64 payout_amount = 6;
    int64 valid_amount = 7;
    int64 fee_amount = 8;
    string wallet_token = 9;
}

Response

Response :

message walletRes {
    string request_id = 1;
    RS status = 6; 
    int64 balance = 7; 
}

Balance

This endpoint balance.

gRPC Request

Method:

rpc balance (BalanceReq) returns (BalanceRes) {}

method api.gateway.WalletProtocolService.balance

Query Parameters

Query Parameters :

message BalanceReq {
    string member_id = 1;
    string game_id = 2;
    string wallet_token = 3;
}

Response

Response :

message BalanceRes {
    int64 balance = 2;
    RS status = 3; 
}

Watch Balance

• use stream

there is notification after a user's balance changed, then using Balance api to get the user's newest balance.

The command returns Body structured like this:

{
  "member_id": 2
}

gRPC Request

Method:

rpc watchBalance (BalanceReq) returns (BalanceRes) {}

method api.gateway.WalletProtocolService.watchBalance

Query Parameters

no need any parameter

Response

Response :

message BalanceRes {
    string member_id = 1;
    int64 balance = 2; 
    RS status = 3;
}

Record

Record URL for Details

{DS_JWT_Token} PAYLOAD:DATA:

{
  "exp": 1600853001,
  "g": "F1001",
  "gs": "5f6b03745451a17e528b3275"
}

1. DS offers a url of bet record to show the detail, Game Provider have to implement the url domain/detail/{DS_JWT_Token}?lang={lang}
2. Game Provider auth the {DS_JWT_Token} after receiving the url, and according to the parameter to show the detail of the record.

Response Statuses

The DS API uses the following Response Statuses codes:

To Response Statuses, use this code:

syntax = "proto3";
package api.gateway;

// Response Statuses
enum RS {

    ERROR_UNKNOWN = 0;
    OK = 1;

    ERROR_INVALID_AGENT =  2;
    ERROR_INVALID_TOKEN = 3;
    ERROR_INVALID_GAME = 4;

    ERROR_WRONG_CURRENCY = 5;
    ERROR_NOT_ENOUGH_MONEY = 6;
    ERROR_USER_DISABLED = 7;
    ERROR_INVALID_SIGNATURE = 8;

    ERROR_TOKEN_EXPIRED = 9;
    ERROR_WRONG_SYNTAX = 10;
    ERROR_WRONG_TYPES = 11;

    ERROR_DUPLICATE_TRANSACTION = 12;
    ERROR_TRANSACTION_DOES_NOT_EXIST = 13;
    ERROR_TRANSACTION_ROLLED_BACK = 14;
    ERROR_TRANSACTION_ALREADY_PAYOUT = 15;
}