1

Table of Contents
1. Introduction

2. Context

2.1 Audience

2.2 Terms & Definitions

3. Overview

3.1 Workflows

1. Player Authentication Flow

2. Financial Flow

3.2 Services & Format

3.3 Error Handling

4. API Functions

5. Security and Authorization

5.1 Authorization for API Calls

5.2 OAuth Authorization for API Calls (Obsolete)

6. Player Authentication

6.1 Sequence Diagram

6.2 Lobby Endpoint

6.3 Player Authorization

6.4 Player Deauthorization

7. External Wallet Integration

7.1 Sequence Diagram

7.2 Retries

7.3 Wallet Balance

7.3.1 Get a specific player’s balance

7.3.2 Get grand total of all players’ balance (Obsolete)

7.3.3 Get all players' balances (Obsolete)

7.4 Wallet Credit

7.5 Wallet Debit

7.6 Reporting Methods

KINGMAKER - Operator API Integration Guide v1.25

 2

7.6.1 Transfer History

7.6.2 Bet Transaction History (Obsolete)

7.6.3 Game History

7.6.4 Bet History

7.6.5 Game History from Game Provider

7.6.6 Transfer History using transaction identifier

7.6.7 Bet History Total

7.6.8 Jackpot Win History (Obsolete)

7.6.9 Jackpot Win History Total (Obsolete)

7.6.10 Player History Total

7.6.11 Reward History

8. Single Wallet Integration

8.1 Sequence Diagram

8.2 Client-Server Authorization

8.3 Debit

8.4 Credit

8.5 Reward

8.6 Get Balance

8.7 Transaction Grouping

8.8 Returning Error Responses

8.9 Errors and Retry Handling

1) Bet Placement

2) Settlement

8.10 Use Case of Single Wallet Integration

9. Direct Game Launch

9.1 Game List

9.2 Game Launcher

9.3 Launch Games

1) Generate a brand access token (please ignore this step if you are new integration)

2) Generate a player token

3) Get a game list from Game List API

KINGMAKER - Operator API Integration Guide v1.25

 3

4) Launch the game using Game Launcher

9.4 Direct Bet History (Obsolete)

9.5 Demo Game Launcher

9.6 Launch Demo Games

1) Generate a brand access token (please ignore this step if you are new integration)

2) Get a game list from Game List API

3) Launch the game using Demo Game Launcher

Appendix

Appendix A - Table of OAuth Errors

Appendix B - Supported HTTP Status Codes

Appendix C - VIP Levels

Appendix D - Languages

Appendix E - Currencies

Appendix F - Transaction Types (txtype)

Appendix G - Bonus Types (bonustype)

Appendix H - Game Types

Appendix I - Table of Errors for External Wallet Integration

Appendix J - Table of Errors for Single Wallet Integration

Appendix K - Table of Game Providers

Appendix L - Platform Types

Appendix M - Table of Games Having In-Game Fund Transfer

Version History

KINGMAKER - Operator API Integration Guide v1.25

 4

1. Introduction
This document provides an overview of the technical activities required for an Operator to integrate with
Kingmaker (KM).

The document provides details for the exchange of messages, the message structure, the list of method calls and
parameters used in the interface, the returning codes used to interpret responses, and examples of the requests
and responses.

2. Context
2.1 Audience
This document is intended for technical audiences assumed to possess basic knowledge in web services, Internet
communications protocols, and proficiency in a programming language.

2.2 Terms & Definitions

Term Definition

UGS Refers to KM ’s system or Unified Gaming Server.

Operator/Licensee The site operator, who licenses the KM system.

Game Provider 3rd party provider of game content that is integrated with KM .

BO Backoffice

Player Customer of the Operator and user of the KM Lobby and Games

3. Overview
KM Unified Gaming Server (UGS) is a remote gaming server (RGS) that provides a single integration point to
multiple game providers. To integrate with the server, there are 2 key workflows that need to be implemented by
the Operator.

3.1 Workflows
1. Player Authentication Flow
a. To make players play KM games from the Operator site, the Operator must send the player
information to the KM Game Lobby along with an authentication token. This token is also sent
from the server side to KM in order to authenticate the player when he arrives at the KM Game
Lobby.

b. KM authenticates the incoming player using the token sent by the Operator.

c. Once authenticated, the player may play any of the KM games.

KINGMAKER - Operator API Integration Guide v1.25

 5

2. Financial Flow
a. External Wallet

i. KM maintains a wallet for each player. The wallet must be funded for the player to play
games on the platform.
ii. Fund-in, fund-out, and balance requests are initiated by the Operator to UGS.

b. Single Wallet

i. KM does not maintain a wallet for each player, but proxies the request to the Operator.
ii. Wallet requests are initiated by UGS to the Operator.

KM UGS Integration Overview Diagram

3.2 Services & Format

KM implements a REST-ful API, but does not adhere strictly to all REST principles. Please refer to RFC 2616 for more
information about REST.

All service calls use either the POST or GET verb and JSON format for both request and response (some are CSV
format). GET requests should be sent via the query string, where POST requests should be sent as JSON in the body
of the request.

To indicate the desired content response type, set the Accept (e.g., “application/json”) HTTP Header. When
sending requests, clients are expected to set the Content-Type (e.g., “Content-Type: application/json”) HTTP
Header.

KINGMAKER - Operator API Integration Guide v1.25

 6

Example request

GET /api/player/balance?userid=fa39953d&cur=THB HTTP/1.1

Host: staging-api.queenmakergames.co
Authorization: Bearer VKgMKCqIQc28cf1PDDoS46Fi6ILBikQo6920Fx3ULLm3LkeXsbiIntO3VyLn4bmUp
Content-Type: application/json
Accept: application/json

Example response
{
"cur": "THB",
"bal": 550
}

3.3 Error Handling

In general, when the HTTP status code of an API method’s response is not 200, that means error(s) happened, and
the API client can examine the error properties in the returned response to get error code and message, shown as
the following table. See Appendix I for external wallet integration and Appendix J for single wallet integration.

Parameter Definition Required (Y/N) Type

err Error code larger than zero. N Integer

errdesc Description of error. N String

Example response
{
"err": 900,
"errdesc": "System Error"
}

KINGMAKER - Operator API Integration Guide v1.25

 7

4. API Functions
The table below lists the API methods introduced in this document with function brief and applied scenarios for
easy navigation and application.

HTTP
Chapter Category Functions Applied Scenarios/ Description
Method

Security Get Access Token Security authentication for all

5 POST
Authentication (Get Brand Token) further API calls

Player Authorization
POST Enable a player to play KM games
(Get Player Token)
Player
6
Authorization
To remove all active sessions for
Player Deauthorization POST
the given player

Get Wallet Balance 1. For players to check the balance

GET
1. Get a specific player’s balance amount in their wallet

External Deposit money to player’s KM

Wallet Credit (Fund-in) POST
7 (Multiple) Wallet wallet
Integration
Withdraw money from player’s KM
Wallet Debit (Fund-out) POST
wallet

Transfer History Player’s fund-in and fund-out

GET
(Player Fund-in/out) history

Game history displays the detailed

Game History GET
information of the round

Most commonly used reporting

Bet History GET
method with detailed bet record

Game History from Game Return data in the format that the
GET
Provider game provider returns
Reporting Transfer History using transaction Used to get players’ fund transfer
7 GET
Methods identifier by transaction identifier

Get the summarized amounts of

Bet History Total GET
bet record on hourly query base

Get the summarized amounts of

bet record by player on hourly
Player History Total GET
query base in a specified period of
time

Get players’ rewards for a specified

Reward History GET
tournament date/time range

Security authentication for all

Get Access Token POST
further API calls
Single Wallet
8
Integration
KINGMAKER - Operator API Integration Guide v1.25
 8

When players place bet, wallet

*For Single Wallet Debit (Place Bet) POST
will be deducted
Integration, it is
KM that sends When bet settlement is win, tie,
out the request Credit (Settle Bet) POST
etc, player’s wallet will be funded
to Operator.
Reward POST Used for rewarding players

For KM to get the balance

Get Wallet Balance POST
information of the player

For operator to get a list of games

Get Game List (optional) GET
for a specific brand

Game Launcher To launch the game directly

Direct Game GET
(build Game Launch URL) without entering KM Lobby
9 Launch
Operator can open web page via
Direct Bet History GET valid player token to check player’s
bet history

5. Security and Authorization

Back to Function List

5.1 Authorization for API Calls

Custom HTTP headers are required when calling KM APIs (those in section 6, 7, 9 and 10). The said headers are
used to verify that the Operator is authorized to communicate with KM APIs. Below are the headers needed.

Name Definition

X-QM-ClientId The Operator’s unique ID, provided at setup time. Can be changed on demand.

X-QM-ClientSecret The Operator’s secret key, provided at setup time. Can be changed on demand.

5.2 OAuth Authorization for API Calls (Obsolete)

Note: This API is no longer supported. Please refer to section 5.1 for the authentication mechanism.

6. Player Authentication
Back to Function List

KINGMAKER - Operator API Integration Guide v1.25

 9

In order to authenticate a player to the KM Game Lobby, an authorization token is requested by the Operator,
which is then passed in the query string when launching the lobby.

6.1 Sequence Diagram

The sequence of authentication is described in the diagram below:

6.2 Lobby Endpoint

A KM Game Lobby endpoint will be provided to the Operator at setup time.

Endpoint URL Example: https://<KMLobbyServerURL>/{lobby_path}?token={authtoken}

To launch the KM lobby, the Operator replaces {lobby_path} with the lobby path configured in KM BO, and replaces
{authtoken} with the token generated during player authorization, which will be validated by KM server.

Important: KM Game Lobby supports different platform types, e.g., desktop and mobile. If a player token is
authorized for desktop use but tries to access mobile lobbies, KM will respond to an error page to indicate an
invalid operation with the message: “You are trying to access the wrong lobby platform”.

Endpoint URL Example for maintenance page:

https://<KMLobbyServerURL>/{lobby_path}?token={authtoken}&maintenanceUrl={maintenanceUrl}

If you would like to display your own maintenance page, you may replace {maintenanceUrl} with your maintenance
page URL.

KINGMAKER - Operator API Integration Guide v1.25

 10

6.3 Player Authorization

The Player Authorize method is called by the Operator to get an auth token, and to pass updated player
information to KM . If the specified player account does not exist in the KM system, it will be created, otherwise
updated.

When this method is called, it is assumed that the player is active in the Operator’s system, as KM will not check
the player’s status with the Operator. If the Operator wishes to deactivate a player session, it must call the Player
Deauthorize method.

Important: When calling this API, make sure the correct value of parameter ‘istestplayer’ is passed in. If
istestplayer=false is passed in, the player will be created in KM as a REAL player, and it cannot be changed to a test
player via API.

URL: https://<KMAPIServerURL>/api/player/authorize
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Required
Parameter Definition Type
(Y/N)

Player client IP address. KM will validate whether the client’s IP address

String
ipaddress has changed. If so, player login will fail when attempting to use the Y
Max length: 40
authtoken.
Friendly username of the player used for display. Uniqueness is not String
username Y
enforced, e.g., james_johnson Max length: 50
Unique identifier of the player, e.g., fc533ace-bb15
String
userid This is case-insensitive, meaning fc533ace-bb15 and FC533ace-bb15 are Y
Max length: 50
the same player to KM .
String (ISO 639-1
lang Language code used by the player. See Appendix D Y and ISO 3166-1)
Length: 5
String (ISO 4217)
cur Currency that the player is using to play the game. See Appendix E. Y
Length: 3
VIP level of the player, used to set betting limits.
betlimitid Y Integer
See Appendix C.
Whether a player is a test player for the Operator (a.k.a. house player).

Important: Please ensure to set this parameter to true for test players. Boolean
istestplayer Y
This value cannot be changed once a player is created in KM , i.e., a test (true or false)
player cannot be converted to a real player via API, and vice versa. If
this parameter is not provided, it will be default to false.
Integer
platformtype The platform the player comes from. See Appendix L. Y

URL to send the player to Operator’s login page. If this is not provided, String
loginurl N
the value configured for the brand in KM will be used. Max length: 255

KINGMAKER - Operator API Integration Guide v1.25

 11

URL to send the player to replenish their balance. If this is not provided, String
cashierurl N
the value configured for the brand in KM will be used. Max length: 255
URL to send the player for customer service. If this is not provided, the String
helpurl N
value configured for the brand in KM will be used. Max length: 255
URL to send the player for terms of service. If this is not provided, the String
termsurl N
value configured for the brand in KM will be used. Max length: 255

Return Parameters:
Parameter Definition Required (Y/N) Type

Authorization token generated by the Operator to uniquely

identify the player’s session. Also called player token. This
String
authtoken value is used in the KM Game Lobby (see Section 6.2) and Y
Max length: 2000
Direct Game Launch (see Section 9.2).
The default timeout of the player token is 1 day (24 hours).

Whether this is a new player that the KM has not encountered Boolean
isnew Y
before. (true or false)

Example Calls:
Request

POST /api/player/authorize HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer K5ML65OcQAStYHtTLY2dArzwGmNbkY2E3EMKgS6sbWTlN2v0cC073BmTE9p
Content-Type: application/json
Accept: application/json

{
"ipaddress":"123.123.1.95",
"username":"john",
"userid":"12345",
"lang":"zh-CN",
"cur":"THB",
"betlimitid":1,
"platformtype":1,
"istestplayer":false
}

Response

Successful result:

{
"authtoken":"q83MsSyoD9FmkZj2g8tYTI2nEmbDEsnpN43QcQ2VBbSgbiH1DmrKkbpyDjjWuzjeML0jr03giFqLsnpaQ3ZPEAhwa
y8LWwBlsn0Ehh0EFOTjsqL8mCL57HSct8JkPNzS1o",
"isnew":false
}

Failed result:

KINGMAKER - Operator API Integration Guide v1.25

 12

See 3.3 Error Handling

6.4 Player Deauthorization

The Player Deauthorize method is called by the Operator to remove all active sessions for the given player. For
example, when a player is logging out from the Operator’s member site, the Operator should call this method to
inform KM , so that players can not enter the KM lobby by picking a URL from the browser's history.

URL: https://<KMAPIServerURL>/api/player/deauthorize
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

String
userid Unique identifier of the player, e.g., fc533ace-bb15 Y
Max length: 50

Return Parameters:
Parameter Definition Required (Y/N) Type

success Whether any token has been updated. Y Boolean (true or false)

String
desc Description of deauthorization result. Y
Max length: 2000

Example Calls:
Request

POST /api/player/deauthorize HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer L9m5F7sQyQiQOSUMbew4qxEMMatRfUS7PES4Hm7lmFh3FIUcCOfakeyI957CD05bM
Content-Type: application/json
Accept: application/json

{
"userid":"0586cecf-4787-49c5-8c35-2118bfa10913"
}

KINGMAKER - Operator API Integration Guide v1.25

 13

Response

Successful result:

{
"success":true,
"desc":"Tokens deauthorized."
}

Failed result:

See 3.3 Error Handling

7. External Wallet Integration

Back to Function List

Financial methods support the transfer of funds to and from the player wallet in the KM system, and provide player
financial information to the Operator.

When using the External Wallet integration method, it is assumed that the Operator will fund in/out to the KM
wallet system. This is in contrast to the Single Wallet approach, in which the Operator’s wallet is used; details are
described in Section 8.

7.1 Sequence Diagram

The sequence of financial method calls is described in the diagram below:

KINGMAKER - Operator API Integration Guide v1.25

 14

KINGMAKER - Operator API Integration Guide v1.25

 15

7.2 Retries

Retries
If a call fails due to a network issue or other problem, a transaction may be retried as many times as required. If
a duplicate transaction ID is received, the KM API will reply with the same result, with the exception of the
balance field, which will be reported in real time to each call. A duplicate flag, “dup”, will be added to the
response for duplicate calls. No dup flag will be added to GET methods, such as the GetBalance method.

In such cases, the Operator should retry the transaction in the following pattern:

Attempt Time interval since last attempt

1 Immediate
2 Immediate
3 5 seconds
4 15 seconds
5 45 seconds
6 135 seconds
7 405 seconds
8 1215 seconds
9 3645 seconds

After the 9th attempt, the Operator should attempt to retry the transaction every 3645 seconds.

7.3 Wallet Balance

The Wallet Balance method is called by the Operator to get balance from the KM wallet system. It supports

1. Get a specific player’s balance

2. Get grand total of all players’ balance (Obsolete)
3. Get all players' balances (Obsolete)

7.3.1 Get a specific player’s balance

Description: Return a specific player’s balance.

URL: https://<KMAPIServerURL>/api/player/balance
HTTP method: GET
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

KINGMAKER - Operator API Integration Guide v1.25

 16

String
userid Unique identifier of the player, e.g., fc533ace-bb15 Y
Max length: 50

Currency that the player is using in the KM system. See String (ISO 4217)
cur Y
Appendix E Length: 3
Return Parameters:
Parameter Definition Required (Y/N) Type

Decimal
bal Amount of the player’s balance. Y
Precision: 6 places

Currency that the player is using in the KM system. String (ISO 4217)
cur Y
See Appendix E Length: 3

Example Calls:
Request

GET /api/player/balance?userid=fc533ace-bb15&cur=THB HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer Ub66Xf2zP6lfXzTFfdmQuOyVIasYXEFONPHC3ObMV5eMkWC0nGHnWdOvCc1SQYMG1
Accept: application/json

Response

Successful result:

{
"bal": 550.88,
"cur": "THB"
}

Failed result:

See 3.3 Error Handling

7.3.2 Get grand total of all players’ balance (Obsolete)

Note: This API is no longer supported.

7.3.3 Get all players' balances (Obsolete)

Note: This API is no longer supported.

KINGMAKER - Operator API Integration Guide v1.25

 17

7.4 Wallet Credit

The Wallet Credit method is called by the Operator to fund the player's wallet in the KM system.

URL: https://<KMAPIServerURL>/api/wallet/credit
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

String
userid Unique identifier of the player, e.g., fc533ace-bb15 Y
Max length: 50
Amount of the credit to the player’s KM wallet. Must be a positive Decimal
amt Y
number and leading zero should not be passed in, e.g., 095.27 Precision: 6 places
Currency of the requested transfer. If this does not match the String (ISO 4217)
cur Y
player’s currency in the KM , an error will be thrown. See Appendix E Length: 3
Identifier of the unique action(include 7.5). If a duplicate txid is String
txid Y
encountered, the previous result is resent with ‘dup’ set to true. Max length: 50
Date (ISO 8601)
timestamp Timestamp with timezone; e.g., 2014-09-25T07:07:31+00:00 N
Length: 25
String
desc Extended description of transaction N
Max length: 255

Return Parameters:
Parameter Definition Required (Y/N) Type

Decimal
bal Amount of the player balance after the transaction is complete. Y
Precision: 6 places

Currency that the player is using in the KM system. String (ISO 4217)
cur Y
See Appendix E Length: 3

Identifier of the unique action. Echoes incoming txid method String

txid Y
parameter value. Max length: 50

GUID
ptxid KM platform transaction ID generated by this action Y
Length: 36

Boolean
dup Duplicate flag indicating whether this is a resent result. Y
(true or false)

Example Calls:
Request

KINGMAKER - Operator API Integration Guide v1.25

 18

POST /api/wallet/credit HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer 9r3GHvizCYek4ddcUNEQyAaGaQio6x6ud9RHV0jNyF2E36o5NsF4scqp9S51Erjxu
Content-Type: application/json
Accept: application/json

{
"userid": "0802a4d4-503c-45c2-baca-1c68fa9844b1",
"amt": 100.88,
"cur": "THB",
"txid": "5bb70123-ae1f-4e3e-9c40-9f35a98d3e8d",
"timestamp": "2015-07-14T23:33:09+00:00",
"desc": null
}

Response

Successful result:

{
"bal": 201.0,
"cur": "THB",
"txid": "5bb70123-ae1f-4e3e-9c40-9f35a98d3e8d",
"ptxid": "02ac4de6-d813-4dff-ac45-26d54db67725",
"dup": false
}

Failed result:
See 3.3 Error Handling

KINGMAKER - Operator API Integration Guide v1.25

 19

7.5 Wallet Debit

The Wallet Debit method is called by the Operator to fund out the player's wallet in the KM system.

URL: https://<KMAPIServerURL>/api/wallet/debit
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

String
userid Unique identifier of the player, e.g., fc533ace-bb15 Y
Max length: 50

Amount of the debit taken from the KM Wallet. Must be a

Decimal
amt positive number and leading zero should not be passed in, e.g., Y
Precision: 6 places
095.27

Currency of the requested transfer. If this does not match the

String (ISO 4217)
cur player’s currency in the KM , an error will be thrown. See Y
Length: 3
Appendix E

Identifier of the unique action(include 7.4). If a duplicate txid is String

txid Y
encountered, the previous result is resent with ‘dup’ set to true. Max length: 50

Timestamp with timezone. Date (ISO 8601)

timestamp N
e.g., 2014-09-25T07:07:31+00:00 Length: 25

String
desc Extended description of transaction N
Max length: 255

Return Parameters:
Parameter Definition Required (Y/N) Type

Decimal
bal Amount of the player balance after the transaction is complete. Y
Precision: 6 places

Currency that the player is using in the KM system. String (ISO 4217)
cur Y
See Appendix E Length: 3

Identifier of the unique action. Echoes incoming txid method String

txid Y
parameter value. Max length: 50

GUID
ptxid KM platform transaction ID generated by this action Y
Length: 36

Boolean
dup Duplicate flag indicating whether this is a resent result. Y
(true or false)

KINGMAKER - Operator API Integration Guide v1.25

 20

Example Calls:
Request

POST /api/wallet/debit HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer 9r3GHvizCYek4ddcUNEQyAaGaQio6x6ud9RHV0jNyF2E36o5NsF4scqp9S51Erjxu
Content-Type: application/json
Accept: application/json

{
"userid": "0802a4d4-503c-45c2-baca-1c68fa9844b1",
"amt": 100.66,
"cur": "THB",
"txid": "6063c527-4440-4adb-9b1c-3c98f829ae30",
"timestamp": "2015-07-14T23:37:37+00:00",
"desc": null
}

Response

Successful result:
{
"bal": 101.05,
"cur": "THB",
"txid": "6063c527-4440-4adb-9b1c-3c98f829ae30",
"ptxid": "b326612b-b500-4afa-a9bf-346c70925f66",
"dup": false
}

Failed result:
See 3.3 Error Handling

7.6 Reporting Methods

Back to Function List

All reporting methods return data in either JSON or CSV format.

There are 9 methods:

● history/transfers
● history/bettransaction
● history/game
● history/bets
● history/transfers/{txid}
● history/bets/total
● history/jackpots
● history/jackpots/total
● history/bets/players/total
To retrieve a Player’s bet history, the history/bets method is typically used.

Note:
1. For retrieving the reporting methods,
A) if you intend to retrieve the history every minute, it is suggested to capture 3-minute data at a time.

KINGMAKER - Operator API Integration Guide v1.25

 21

B) if you intend to retrieve the history for a whole day, it is suggested to capture 30-minute data at a
time.

2. The reporting methods provide real-time data with less than 1-minute delay.

7.6.1 Transfer History

This method is used to get players’ fund-in and fund-out history.

Note: You can only search data within the past 45 days.

URL: https://<KMAPIServerURL>/api/history/transfers
HTTP method: GET
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

Unique identifier of the player, e.g, fc533ace-bb15

String
userid If not specified, ALL records from the date range will be N
Max length: 50
returned.

Starting date of the transfer. URL-encode it before

Date (ISO 8601)
startdate sending out the request. Y
Length: 25
e.g., 2014-09-25T07:00:00+00:00

Ending date of the transfer. ‘enddate’ must not be more

than 48 hours past the ‘startdate’.

URL-encode it before sending out the request.

Date (ISO 8601)
enddate e.g., 2014-09-25T08:00:00+00:00 Y
Length: 25
Note the enddate is exclusive, so if you want to get data
for one hour at 2014-09-25 08:00, the startdate and
enddate should be 2014-09-25T08:00:00+00:00 and
2014-09-25T09:00:00+00:00 respectively.

Whether to include test players or not. Boolean

includetestplayers N
Default: false (true or false)

Note:
● It’s not suggested to specify a big range with ‘startdate’ and ‘enddate’, for example 1 hour. That means KM will
return bet records that have been updated during that 1 hour, which means it takes longer to return those data. If
the data is huge, it may time out as well. It’s suggested to specify a 2 to 5-minute range and call this method every
2 to 5 minutes.
● If you decide to call this method every 5 minutes, you may pass a 5-minute range with ‘startdate’ and ‘enddate’ for
each call. For example:
1st call: startdate=2016-06-03T09:00:00+08:00 , enddate=2016-06-03T09:05:00+08:00
2nd call: startdate=2016-06-03T09:05:00+08:00 , enddate=2016-06-03T09:10:00+08:00

KINGMAKER - Operator API Integration Guide v1.25

 22

Return Parameters:
Parameter Definition Type

Identifier of the transfer transaction. This is identical to the txid provided by String
txid
the Operator in the Credit and Debit operations. Max length: 50

Time of the transfer on the KM server, including timezone offset. Date (ISO 8601)
timestamp
e.g., 2014-09-25T07:07:31+00:00 Length: 25

String
userid Unique identifier of the player.
Max length: 50

String
username Display name of the player.
Max length: 50

Identify whether the player of the transfer is a real player or a test player.
1 = Real Player Integer
playertype
2 = Operator Test Player
4 = KM Test Player

Amount of the transfer.

Decimal
amt A positive amount indicates a transfer TO the KM server (Fund In)
Precision: 6 places
A negative amount indicates a transfer FROM the KM server (Fund Out)

Decimal
postbal Amount of the player’s balance after the transfer.
Precision: 6 places

String (ISO 4217)

cur Currency that the player is using in the KM system. See Appendix E
Length: 3

Example Calls:
Request

GET
/api/history/transfers?startdate=2015-08-14T07%3A07%3A31%2B00%3A00&enddate=2015-08-15T08%3A10%3A31%2B00%
3A00 HTTP/1.1
Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer b9LChW4Dwi5E8ZCNsuDEg9qpzUR5tiDgjFWfo9SElGTzO9Ba6oEy5sujfnGFkg1y6
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
txid,timestamp,userid,username,playertype,amt,postbal,cur
6063c527,2015-08-14T08:07:31+00:00,fa39953d,dave,1,200.000000,400.000000,THB
5163d332,2015-08-14T08:08:31+00:00,fa39953e,michael,1,100.000000,300.000000,THB

JSON:
[
{
"txid":"transfer-txid-b34bd12d-a286-4353-a06b-ae80ead3d9f4",
"timestamp":"2017-12-12T10:44:28+08:00",
"userid":"123456789",
"username":"testuser1",

KINGMAKER - Operator API Integration Guide v1.25

 23

"playertype":1,
"amt":10.00,
"postbal":10.00,
"cur":"THB"
},
{
"txid":"transfer-txid-c6aa8f89-383a-4b38-9ed0-01a3173413ba",
"timestamp":"2017-12-12T10:50:14+08:00",
"userid":"123456789",
"username":"testuser1",
"playertype":1,
"amt":10.00,
"postbal":10.00,
"cur":"THB"
}
]

Failed result:
See 3.3 Error Handling

KINGMAKER - Operator API Integration Guide v1.25

 24

7.6.2 Bet Transaction History (Obsolete)

Back to Function List

Note: This API is no longer supported. Please refer to section 7.6.3 or 7.6.4 to get round or bet history
instead.

7.6.3 Game History

Back to Function List

This method can be used to get players’ game history.

Note: You can only search data within the past 45 days.

URL: https://<KMAPIServerURL>/api/history/game
HTTP method: GET
HTTP header: Accept-Encoding(optional): gzip
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Required
Parameter Definition Type
(Y/N)

Unique identifier of the player, e.g, fc533ace-bb15

String
userid If not specified, ALL records for the date range will be N
Max length: 50
returned.
Starting date of the game history (round end). URL-encode
Date (ISO 8601)
startdate it before sending out the request. Y
Length: 25
e.g., 2014-09-25T00:00:00+00:00
Ending date of the game history (round end).’ enddate’ must
not be more than 48 hours past the ‘startdate’.
URL-encode it before sending out the request.
e.g., 2014-09-25T01:00:00+00:00
Date (ISO 8601)
enddate Y
Length: 25
Note the enddate is exclusive, so if you want to get data for
one hour at 2014-09-25 08:00, the startdate and enddate
should be 2014-09-25T08:00:00+00:00 and
2014-09-25T09:00:00+00:00 respectively.
Whether to include test players or not. Boolean
includetestplayers N
Default: false (true or false)

true: return winloss, turnover, validbet with jackpot

contribution Boolean
includejackpotcontribution N
false: return winloss, turnover, validbet without jackpot (true or false)
contribution (default)

Note:
● It’s not suggested to specify a big range with ‘startdate’ and ‘enddate’, for example 1 hour. That means KM will
return bet records that have been updated during that 1 hour, which means it takes longer to return those data. If

KINGMAKER - Operator API Integration Guide v1.25

 25

the data is huge, it may time out as well. It’s suggested to specify a 2 to 5-minute range and call this method every
2 to 5 minutes.
● If you decide to call this method every 5 minutes, you may pass a 5-minute range with ‘startdate’ and ‘enddate’ for
each call. For example:
1st call: startdate=2016-06-03T09:00:00+08:00 , enddate=2016-06-03T09:05:00+08:00
2nd call: startdate=2016-06-03T09:05:00+08:00 , enddate=2016-06-03T09:10:00+08:00

Return Parameters:
Parameter Definition Type

Time that the round starts, including timezone offset. Date (ISO 8601)
roundstart
e.g., 2014-09-25T07:07:31+00:00 Length: 25
Time that the round ends, including timezone offset. Will be null if the Date (ISO 8601)
roundend
round hasn’t ended. e.g., 2014-09-25T07:07:31+00:00 Length: 25
Game Provider’s identifier of the round in which the game transactions take String
roundid
place. All transactions are grouped by round. Max length: 50
UGS internal unique identifier of the round in which the game transactions GUID
ugsroundid
take place. All transactions are grouped by round. Length: 36
Status of the round at the time of reporting. One of: String
roundstatus
Open/Closed Max length: 10
String
userid Unique identifier of the player.
Max length: 50
String
username Display name of the player.
Max length: 50
Identify whether the player of the round is a real player or a test player.
1 = Real Player
playertype Integer
2 = Operator Test Player
4 = KM Test Player
Total amount placed in the round, across all bets. This is a positive number.
Decimal
riskamt Note: this is not consistent with /history/bets, which treats this as a negative
Precision: 6 places
number.
Total amount won in the round, across all bets. This is a positive number. Decimal
winamt
Note: this field is NOT net win(winamt-riskamt), but the bet return. Precision: 6 places
Amount of the player’s balance before the first transaction of the round
Decimal
beforebal Note: because multiple games may be played simultaneously, the difference
Precision: 6 places
in beforebal and postbal may not equal the net win.
Amount of the player’s balance after the last transaction of the round.
Decimal
postbal Note: because multiple games may be played simultaneously, the difference
Precision: 6 places
in beforebal and postbal may not equal the net win.
String (ISO 4217)
cur Currency that the player is using in the KM system. See Appendix E
Length: 3
String
gameprovider Name of the game provider. e.g., "KingMaker QM"
Max length: 50
String
gameprovidercode Game provider code, e.g., "KMQM". See Appendix K
Max length: 50
String
gamename Name of the game, e.g., "Thai Hi Lo 2"
Max length: 50
Game provider’s unique identifier of their game. This is the identifier of the String
gameid
game (e.g., thai-hi-lo-2), not the round. Max length: 50
platformtype The type of game platform. See Appendix L String

KINGMAKER - Operator API Integration Guide v1.25

 26

Max length: 50
String
ipaddress IP address of the player reported by the game provider
Max length: 40
Total turnover in the round, across all bets. This is a positive number.
Note:
Decimal
turnover If ‘includejackpotcontribution’ is false, this field is riskamt -
Precision: 6 places
jackpotcontribution.
If ‘includejackpotcontribution’ is true, this field is riskamt.

Total valid bet in the round, across all bets. This is a positive number.
Note:
Decimal
validbet If ‘includejackpotcontribution’ is false, this field is riskamt - (tie bet) -
Precision: 6 places
jackpotcontribution.
If ‘includejackpotcontribution’ is true, this field is riskamt - (tie bet).

Amount contributed to Jackpot in player's currency Decimal

jackpotcontribution
Note: it will only be seen If the brand takes jackpot Precision: 6 places

Example Calls:
Request

GET
/api/history/game?startdate=2016-09-23T07%3A07%3A31%2B00%3A00&enddate=2016-09-24T07%3A07%3A31%2B00%3A0
0 HTTP/1.1
Host: staging-api.queenmakergames.co
Accept-Encoding: gzip
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer H11UHxa6l8gwQJPEmd9M8MumVyEIWntvmZRTjQGQX7InPYhcVzgcYkpR3WjaGqRNi
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
roundstart,roundend,roundid,ugsroundid,roundstatus,userid,username,playertype,riskamt,winamt,beforebal,postbal,cur,game
provider,gameprovidercode,gamename,gameid,platformtype,ipaddress,turnover,validbet,jackpotcontribution
2017-04-05T14:03:20+08:00,2017-04-05T14:04:37+08:00,2166911491372199695,1e153b91-c519-e711-80d3-0050568c15dc,C
losed,02_REAL_thb_en-us,RP02_thb_en-us,1,100.000000,215.700000,300368.790000,300484.490000,THB,KingMaker
QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Desktop,220.134.63.126,100.000000,100.000000,0.000000
2017-04-05T14:01:30+08:00,2017-04-05T14:02:30+08:00,R21704050564,3652244f-c519-e711-80d3-0050568c15dc,Closed,02
_REAL_thb_en-us,RP02_thb_en-us,1,30.000000,0.000000,300398.790000,300368.790000,THB,KingMaker QM,KMQM,Thai Hi
Lo 2,thai-hi-lo-2,Desktop,220.134.63.126,30.000000,30.000000,0.000000
2017-04-05T13:57:53+08:00,2017-04-05T13:57:53+08:00,ugs-stage-21420928,a5e089ce-c419-e711-80d3-0050568c4a33,Clos
ed,01_REAL_thb_en-us,RP01_thb_en-us,1,200.000000,0.000000,14320153.850000,14319953.850000,THB,KingMaker
QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Desktop,220.134.63.126,200.000000,200.000000,0.000000
2017-04-05T13:55:35+08:00,2017-04-05T13:55:36+08:00,ugs-stage-21420927,2a1a7a7c-c419-e711-80d3-0050568c4a33,Clos
ed,01_REAL_thb_en-us,RP01_thb_en-us,1,100.000000,0.000000,14320253.850000,14320153.850000,THB,KingMaker
QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Desktop,220.134.63.126,100.000000,100.000000,0.000000

JSON:
[
{
"roundstart":"2017-12-12T11:12:58+08:00",
"roundend":"2017-12-12T11:12:58+08:00",
"roundid":"bethist-roundid-82c4c694-e918-43ec-9c87-315203d199e7",
"ugsroundid":"e5d45456-eade-e711-b367-7824af8296b8",
"roundstatus":"Closed",

KINGMAKER - Operator API Integration Guide v1.25

 27

"userid":"123456789",
"username":"testuser1",
"playertype":1,
"riskamt":10.000,
"winamt":15.000,
"beforebal":100.00,
"postbal":105.00,
"cur":"THB",
"gameprovider":"KingMaker QM",
"gameprovidercode":"KMQM",
"gamename":"Thai Hi Lo 2",
"gameid":"thai-hi-lo-2",
"platformtype":"Desktop",
"ipaddress":"184.70.137.34",
"turnover":10.000,
"validbet":10.000,
"jackpotcontribution":0.000000
},
{
"roundstart":"2017-12-12T11:31:57+08:00",
"roundend":"2017-12-12T11:31:58+08:00",
"roundid":"bethist-roundid-51def82c-1939-4700-a1c7-a33f97c5bfd0",
"ugsroundid":"ef4ec5fd-ecde-e711-b367-7824af8296b8",
"roundstatus":"Closed",
"userid":"123456789",
"username":"testuser1",
"playertype":1,
"riskamt":10.000,
"winamt":15.000,
"beforebal":100.00,
"postbal":105.00,
"cur":"THB",
"gameprovider":"KingMaker QM",
"gameprovidercode":"KMQM",
"gamename":"Thai Hi Lo 2",
"gameid":"thai-hi-lo-2",
"platformtype":"Desktop",
"ipaddress":"184.70.137.34",
"turnover":10.000,
"validbet":10.000,
"jackpotcontribution":0.000000
}
]

Failed result:
See 3.3 Error Handling

7.6.4 Bet History

Back to Function List

The Bet History method is used to get bet records for a specified date/time range. This is the suggested method for
Operators to get players’ bet history. When a round status is changed (for example, from Open to Closed), the
round’s last update time will change, and you can use this method to get bet records that have been updated
during the time specified with ‘startdate’ and ‘enddate’ parameters.

By default, this method returns both settled and unsettled bets. If ‘issettled’ parameter is set to true, this method
will return settled bets only.

KINGMAKER - Operator API Integration Guide v1.25

 28

Note: You can only search data within the past 45 days.

URL: https://<KMAPIServerURL>/api/history/bets
HTTP method: GET
HTTP header: Accept-Encoding(optional): gzip
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Required
Parameter Definition Type
(Y/N)

Unique identifier of the player, e.g., fc533ace-bb15

String
userid If not specified, ALL records for the date range will be N
Max length: 50
returned.

Starting date of the game history (compared to the last

update time of a round). Date (ISO 8601)
startdate Y
URL-encode it before sending out the request. Length: 25
e.g., 2014-09-25T00:00:00+00:00

Ending date of the game history (round end).

‘enddate’ must not be more than 48 hours past the
‘startdate’. URL-encode it before sending out the request.
e.g., 2014-09-25T01:01:00+00:00
Date (ISO 8601)
enddate Y
Length: 25
Note the enddate is exclusive, so if you want to get data for
one hour at 2014-09-25 08:00, the startdate and enddate
should be 2014-09-25T08:00:00+00:00 and
2014-09-25T09:00:00+00:00 respectively.

Whether to include test players or not. Boolean

includetestplayers N
Default: false (true or false)

true: return settled bets only. Boolean

issettled N
false: return settled and unsettled bets. (default) (true or false)

true: return winloss, turnover, validbet with jackpot

contribution Boolean
includejackpotcontribution N
false: return winloss, turnover, validbet without jackpot (true or false)
contribution (default)

Note:
● It’s not suggested to specify a big range with ‘startdate’ and ‘enddate’, for example 1 hour. That means KM will
return bet records that have been updated during that 1 hour, which means it takes longer to return those data. If
the data is huge, it may time out as well. It’s suggested to specify a 2 to 5-minute range and call this method every
2 to 5 minutes.
● If you decide to call this method every 5 minutes, you may pass a 5-minute range with ‘startdate’ and ‘enddate’ for
each call. For example:
1st call: startdate=2016-06-03T09:00:00+08:00 , enddate=2016-06-03T09:05:00+08:00
2nd call: startdate=2016-06-03T09:05:00+08:00 , enddate=2016-06-03T09:10:00+08:00

KINGMAKER - Operator API Integration Guide v1.25

 29

Return Parameters:
Parameter Definition Type

KM internal bet ID. This is the unique key that can be used to identify a specific bet.
Important: you may get the same bet with different status across multiple API calls.
For example:
GUID
ugsbetid 1. First call returns ugsbetid=1, betid=XYZ, roundstatus=Open
Length: 36
2. Second call returns ugsbetid=1, betid=XYZ, roundstatus=Closed

The ‘betid’ mentioned above is an external bet ID, see ‘betid’ parameter below.
String
txid Identifier of the transaction or bet from the game provider.
Max length: 50
External bet ID (from a game provider).
String
betid Do not use this field to identify a specific bet record, because there could be the
Max length: 64
same bet ID from different game providers.
The time when this bet was placed and recorded at KM server, including timezone Date (ISO 8601)
beton
offset. e.g., 2014-09-25T07:07:31+00:00 Length: 25

The time when this bet was closed, including timezone offset. Date (ISO 8601)
betclosedon
e.g., 2014-09-25T07:07:31+00:00 Length: 25

The time when this bet was updated, including timezone offset. Date (ISO 8601)
betupdatedon
e.g., 2014-09-25T07:07:31+00:00 Length: 25

Timestamp that the Game Provider processed the action. If not provided by Game
Date (ISO 8601)
timestamp Provider, it is the timestamp that UGS processes the action.
Length: 25
e.g., 2014-09-25T07:07:31+00:00

Game Provider’s identifier of the round in which the game transactions take place. String
roundid
All transactions are grouped by round Max length: 50

Status of the round at the time of reporting. One of: String

roundstatus
Open/Closed Max length: 10

String
userid Unique identifier of the player.
Max length: 50

String
username Display name of the player.
Max length: 50

Bet placement amount (stake). The value is negative, as it represents a debit from Decimal
riskamt
the player’s account. Precision: 6 places

Winning amount of the bet. The value is positive when a win is credited to the Decimal
winamt
player’s account, or zero if no win occurs. Precision: 6 places

Net return of the bet to the player

Note: If ‘includejackpotcontribution’ is false, this field is Decimal
winloss
(winamt+(riskamt+jackpotcontribution)). Precision: 6 places
If ‘includejackpotcontribution' is true, this field is (winamt+riskamt).

Amount of the player’s balance before this bet transaction.

Decimal
beforebal Note: because multiple games may be played simultaneously, the difference in
Precision: 6 places
beforebal and postbal may not equal the net win.

Amount of the player’s balance after this bet transaction.

Decimal
postbal Note: because multiple games may be played simultaneously, the difference in
Precision: 6 places
beforebal and postbal may not equal the net win.

String (ISO 4217)

cur Currency that the player is using in the KM system. See Appendix E
Length: 3

KINGMAKER - Operator API Integration Guide v1.25

 30

String
gameprovider Name of the game provider, e.g., "KingMaker QM"
Max length: 50

String
gameprovidercode Game provider code, e.g., "KMQM". See Appendix K
Max length: 50

String
gamename Name of the game, e.g., "Thai Hi Lo 2"
Max length: 50

Game provider’s unique identifier of their game. This is the identifier of the game String
gameid
(e.g., thai-hi-lo-2), not the round. Max length: 50

String
platformtype The type of game platform. See Appendix L
Max length: 50

ipaddress String
IP address of the player reported by the game provider
(optional) Max length: 40

String
bettype Always “PlaceBet”
Max length: 30

Play type of the game, defined by game providers.

String
playtype e.g., BaBank, BaDeal, DtTigr, DtDrag, etc.
Max length: 2000
Note: this value could be displayed as a json string, please handle the escape string.

Identify whether the player of the transaction is a real player or a test player.
1 = Real Player
playertype Integer
2 = Operator Test Player
4 = KM Test Player

Turnover amount. This is a positive number.

Note: Decimal
turnover
If ‘includejackpotcontribution’ is false, this field is riskamt - jackpotcontribution. Precision: 6 places
If ‘includejackpotcontribution’ is true, this field is riskamt.

Valid bet amount. This is a positive number.

Note:
Decimal
validbet If ‘includejackpotcontribution’ is false, this field is riskamt - (tie bet) -
Precision: 6 places
jackpotcontribution.
If ‘includejackpotcontribution’ is true, this field is riskamt - (tie bet).

Amount contributed to Jackpot in player's currency. Decimal

jackpotcontribution
Note: it will only be seen If operator takes jackpot Precision: 6 places

The ID of the jackpot pool hit

String
jackpotid Note: it will only be seen If operator takes jackpot, and will be empty if player does
Max length:50
not hit jackpot

Jackpot winning amount of the bet

Decimal
jackpotwinamt Note: it will only be seen If operator takes jackpot, and will be 0 if player does not
Precision: 6 places
hit jackpot

Example Calls:
Request

GET
/api/history/bets?startdate=2017-04-05T01%3A05%3A01%2B08%3A00&enddate=2017-04-05T02%3A05%3A01%2B08%3A00
HTTP/1.1
Host: staging-api.queenmakergames.co
Accept-Encoding: gzip
X-QM-ClientId: 0e1d1034f981499e

KINGMAKER - Operator API Integration Guide v1.25

 31

X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer MqtZWhfDu6tCKzDjE2tjEkjFYJylBaYoZO4vlUqATP4HeUas8hDI1pJp4oakZdxsp
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
ugsbetid,txid,betid,beton,betclosedon,betupdatedon,timestamp,roundid,roundstatus,userid,username,riskamt,winamt,winl
oss,beforebal,postbal,cur,gameprovider,gameprovidercode,gamename,gameid,platformtype,ipaddress,bettype,playtype,play
ertype,turnover,validbet,jackpotcontribution,jackpotid,jackpotwinamt
f6012704-e99c-492b-a612-43f23f6210b4,ugsstg-260985228-520996621,ugs-260985228,2017-04-05T01:05:02+08:00,2017-
04-05T01:05:02+08:00,2017-04-05T01:05:02+08:00,2017-04-04T17:05:02+08:00,ugs-260985228,Closed,f001,dave,-2.00000
0,0.000000,-2.000000,284.400000,282.400000,THB,KingMaker QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Mobile, 222.134.63.126,
PlaceBet,,1,2.000000,2.000000, 0.000000,,0.000000
3cfcb09f-3d84-4b76-bd84-a048474f766c,ugsstg-260985267-520996697,ugs-260985267,2017-04-05T01:05:05+08:00,2017-0
4-05T01:05:05+08:00,2017-04-05T01:05:05+08:00,2017-04-04T17:05:05+08:00,ugs-260985267,Closed,f001,dave,-2.000000,
0.000000,-2.000000,282.400000,280.400000,THB,KingMaker QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Mobile, 222.134.63.126,
PlaceBet,,1,2.000000,2.000000, 0.000000,,0.000000
0df93340-b0e0-4fa0-a6f9-58b8914e13d4,ugsstg-260985301-520996765,ugs-260985301,2017-04-05T01:05:08+08:00,2017-
04-05T01:05:08+08:00,2017-04-05T01:05:08+08:00,2017-04-04T17:05:08+08:00,ugs-260985301,Closed,f001,dave,-2.00000
0,0.000000,-2.000000,280.400000,278.400000,THB,KingMaker QM,KMQM,Thai Hi Lo 2,thai-hi-lo-2,Mobile, 222.134.63.126,
PlaceBet,"{""commission"":2.000000}",1,2.000000,2.000000, 0.000000,171021,12346789.000000

JSON:
[
{
"ugsbetid":"12708026-04b8-408c-886f-9495d6e727c0",
"txid":"bethist-txid-c73e1c01-0e15-4352-85cb-2add25a3d4b0",
"betid":"bethist-betrecid-2eb0f68a-95ae-472f-b984-706ef59ae337",
"beton":"2017-12-12T11:08:10+08:00",
"betclosedon":"2017-12-12T11:08:11+08:00",
"betupdatedon":"2017-12-12T11:08:11+08:00",
"timestamp":"2017-12-12T11:08:10+08:00",
"roundid":"bethist-roundid-4478d228-7cf4-4c27-966d-11886efb5473",
"roundstatus":"Closed",
"userid":"123456789",
"username":"testuser1",
"riskamt":-10,
"winamt":15,
"winloss":5,
"beforebal":100,
"postbal":105,
"cur":"THB",
"gameprovider":"KingMaker QM",
"gameprovidercode":"KMQM",
"gamename":"Thai Hi Lo 2",
"gameid":"thai-hi-lo-2",
"platformtype":"Desktop",
"ipaddress":"184.70.137.34",
"bettype":"PlaceBet",
"playtype":null,
"playertype":1,
"turnover":10,
"validbet":10,
"jackpotcontribution":0,
“jackpotid”:””,
“jackpotwinamt”:0

KINGMAKER - Operator API Integration Guide v1.25

 32

},
{
"ugsbetid":"1ce6edf7-6587-48e6-83c3-7b90833c7e03",
"txid":"bethist-txid-b32b6ad9-9180-40bd-9442-b2c637d13669",
"betid":"bethist-betrecid-9a05cb88-c571-4367-a500-2cbbbd1df1b3",
"beton":"2017-12-12T11:09:45+08:00",
"betclosedon":"2017-12-12T11:09:45+08:00",
"betupdatedon":"2017-12-12T11:09:45+08:00",
"timestamp":"2017-12-12T11:09:45+08:00",
"roundid":"bethist-roundid-c031556c-fc85-4130-aa35-382b7d09879c",
"roundstatus":"Closed",
"userid":"123456789",
"username":"testuser1",
"riskamt":-10,
"winamt":15,
"winloss":5,
"beforebal":100,
"postbal":105,
"cur":"THB",
"gameprovider":"KingMaker QM",
"gameprovidercode":"KMQM",
"gamename":"Thai Hi Lo 2",
"gameid":"thai-hi-lo-2",
"platformtype":"Desktop",
"ipaddress":"184.70.137.34",
"bettype":"PlaceBet",
"playtype":"{\"commission\":2.000000}",
"playertype":1,
"turnover":10,
"validbet":10,
"jackpotcontribution":0,
“jackpotid”:”17102”,
“jackpotwinamt”:123456
}
]

Failed result:
See 3.3 Error Handling

7.6.5 Game History from Game Provider

Back to Function List

Game history provided by Game Provider is also available through KM Operator API.

Please note that, different from the History API methods described in previous sections, this API returns what a
Game Provider API returns. That means, if a Game Provider returns HTML or XML, this API returns HTML or XML
as it is. That also means the Operator needs to deal with various formats from different game providers.

Note:
1) Returned data of game history from game provider is within 45 days; if the round is over 45 days, the API
will return an error message as follow:
{
"err": 900,
"errdesc": "Round started more than 45 days ago."
}

KINGMAKER - Operator API Integration Guide v1.25

 33

URL: https://<KMAPIServerURL>/api/history/providers/{gpcode}/rounds/{roundid}/users/{userid}?lang={lang}
HTTP method: GET
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

String
userid Unique identifier of the player, e.g., fc533ace-bb15 Y
Max length: 50

String
gpcode Game provider code, e.g., "KMQM". See Appendix K Y
Max length: 50
Game Provider’s identifier of the round in which the game
transactions take place.

String
roundid URL-encode it before sending out the request. Y
Max length: 50
e.g., the roundid for DreamTech (DT) looks like
dragonball#b3652435657, please send with
dragonball%23b3652435657.
lang Language code used by the player. If the language code is empty or N String
(optional) not supported, the default language: en-US will be used.
Length: 5
See Appendix D for the list of language codes.

Return:
Game Provider Content Type Response

{
Red Tiger
OneGame application/json “url”: “<string>”
KingMaker }

7.6.6 Transfer History using transaction identifier

Back to Function List

This method is used to get players’ fund transfer by transaction identifier.

Note: You can only search data within the past 45 days.

URL: https://<KMAPIServerURL>/api/history/transfers/{txid}
HTTP method: GET
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

KINGMAKER - Operator API Integration Guide v1.25

 34

Method Parameters:
Parameter Definition Required (Y/N) Type

Identifier of the transfer transaction. This is identical to the txid Y String

txid
provided by the Operator in the Credit and Debit operations. Max length: 50

Return Parameters:
Parameter Definition Type

Identifier of the transfer transaction. This is identical to the txid provided by the String
txid
Operator in the Credit and Debit operations. Max length: 50
Time of the transfer on the KM server, including timezone offset. Date (ISO 8601)
timestamp
e.g., 2014-09-25T07:07:31+00:00 Length: 25
String
userid Unique identifier of the player.
Max length: 50
String
username Display name of the player.
Max length: 50
Identify whether the player of the transfer is a real player or a test player.
1 = Real Player Integer
playertype
2 = Operator Test Player
4 = KM Test Player
Amount of the transfer.
Decimal
amt A positive amount indicates a transfer TO the KM server (Fund In)
Precision: 6 places
A negative amount indicates a transfer FROM the KM server (Fund Out)
Decimal
postbal Amount of the player’s balance after the transfer.
Precision: 6 places
String (ISO 4217)
cur Currency that the player is using in the KM system. See Appendix E
Length: 3

Example Calls:
Request

GET /api/history/transfers/6063c527 HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer b9LChW4Dwi5E8ZCNsuDEg9qpzUR5tiDgjFWfo9SElGTzO9Ba6oEy5sujfnGFkg1y6
Accept: application/json

Response

Successful result:
{
"txid":"transfer-txid-cdf302fa-455f-478e-a592-0bc3d9c5f4e3",
"timestamp":"2017-12-12T12:11:16+08:00",
"userid":"123456789",
"username":"testuser1",
"playertype":1,
"amt":10.00,
"postbal":10.00,
"cur":"THB"
}

KINGMAKER - Operator API Integration Guide v1.25

 35

Failed result:
See 3.3 Error Handling

7.6.7 Bet History Total

Back to Function List

This method is used to get the summarized amounts that match the result of invoking history/bets API.
This method supports only hourly basis queries.

Note: You can only search data within the past 45 days.

URL: https://<KMAPIServerURL>/api/history/bets/total
HTTP method: GET
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

Starting date of the game history (compared to the last update time
Date (ISO 8601)
startdate of a round). URL-encode it before sending out the request. Y
Length: 25
e.g., 2014-09-25T00:00:00+00:00

Ending date of the game history (round end).

‘enddate’ must not be more than 48 hours past the ‘startdate’.
URL-encode it before sending out the request.
e.g., 2014-09-25T01:01:00+00:00
Date (ISO 8601)
enddate Y
Length: 25
Note the enddate is exclusive, so if you want to get data for one hour
at 2014-09-25 08:00, the startdate and enddate should be
2014-09-25T08:00:00+00:00 and 2014-09-25T09:00:00+00:00
respectively.

String (ISO 4217)

cur Currency that the player is using in the KM system. See Appendix E N
Length: 3

Return Parameters:
Parameter Definition Type

numberofbets The numbers of Bet placement Integer

Total bet placement amount (stake). The value is negative, as it represents a debit from Decimal
riskamt
the player’s account. Precision: 6 places

Total winning amount of the bet. The value is positive when a win is credited to the Decimal
winamt
player’s account, or zero if no win occurs. Precision: 6 places

Total turnover amount. This is a positive number. Decimal

turnover
Note: this field is riskamt - jackpotcontribution Precision: 6 places

validbet Total valid bet amount. This is a positive number. Decimal

KINGMAKER - Operator API Integration Guide v1.25

 36

Note: this field is riskamt - (tie bet) - jackpotcontribution Precision: 6 places

Decimal
winloss Total net return of the bet to the player (winamt+riskamt).
Precision: 6 places

String (ISO 4217)

cur Currency that the player is using in the KM system. See Appendix E
Length: 3

Identify whether the player of the transaction is a real player or a test player.
1 = Real Player Integer
playertype
2 = Operator Test Player
4 = KM Test Player

Total jackpot winners' win amounts. Decimal

jackpotwinamt
Note: it will only be seen If operator takes jackpot Precision: 6 places

KINGMAKER - Operator API Integration Guide v1.25

 37

Example Calls:
Request

GET
/api/history/bets/total?startdate=2017-04-05T01%3A00%3A00%2B08%3A00&enddate=2017-04-05T02%3A00%3A00%2B08
%3A00 HTTP/1.1
Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer MqtZWhfDu6tCKzDjE2tjEkjFYJylBaYoZO4vlUqATP4HeUas8hDI1pJp4oakZdxsp
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
numberofbets,riskamt,winamt,turnover,validbet,winloss,cur,playertype,jackpotwinamt
9,-1560.000000,1590.000000,1590.000000,1560.000000,30.000000,THB,1,2000.000000

JSON:
[
{
"numberofbets":9,
"riskamt":-1560.00,
"winamt":1590.00,
"turnover":1590.00,
"validbet":1560.000,
"winloss":30.000,
"cur":"THB",
"playertype":1,
"jackpotwinamt":2000.00
}
]

Failed result:
See 3.3 Error Handling

7.6.8 Jackpot Win History (Obsolete)

Back to Function List

Note: This API is no longer supported.

7.6.9 Jackpot Win History Total (Obsolete)

Back to Function List

Note: This API is no longer supported.

7.6.10 Player History Total

Back to Function List

KINGMAKER - Operator API Integration Guide v1.25

 38

This method is used to get the summarized amounts of bet record by player basis in a specified period of time.
This method supports only hourly basis query.

Note: The data is only available for two hours ago.

URL: https://<KMAPIServerURL>/api/history/bets/players/total
HTTP method: GET
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

Unique identifier of the player, e.g., fc533ace-bb15 String

userid N
If not specified, ALL records for the date range will be returned. Max length: 50

Starting date of the game history (round end).

Date (ISO 8601)
startdate URL-encode it before sending out the request. Y
Length: 25
e.g., 2014-09-25T00:00:00+00:00

Ending date of the game history (round end).

‘enddate’ must not be more than 48 hours past the ‘startdate’.
URL-encode it before sending out the request.
e.g., 2014-09-25T01:01:00+00:00
Date (ISO 8601)
enddate Y
Length: 25
Note the enddate is exclusive, so if you want to get data for one
hour at 2014-09-25 08:00, the startdate and enddate should be
2014-09-25T08:00:00+00:00 and 2014-09-25T09:00:00+00:00
respectively.

Boolean
includetestplayers Whether to include test players or not. Default: false N
(true or false)
platform The platform the player comes from. See Appendix L N Integer
true: return summarized amount of rounds with negative winloss. Boolean
returnloss N
false: will not return this data. Default: false (true or false)

true: return winloss, turnover, validbet with jackpot contribution

includejackpotcont Boolean
false: return winloss, turnover, validbet without jackpot N
ribution (true or false)
contribution (default)

Return Parameters:
Parameter Definition Type

String
username Display name of the player.
Max length: 50
Turnover amount. This is a positive number.
Note:
Decimal
turnover If ‘includejackpotcontribution’ is false, this field is riskamt - jackpotcontribution.
Precision: 6 places
If ‘includejackpotcontribution’ is true, this field is riskamt.

validbet Valid bet amount. This is a positive number. Decimal

KINGMAKER - Operator API Integration Guide v1.25

 39

Note: Precision: 6 places

If ‘includejackpotcontribution’ is false, this field is riskamt - (tie bet) -
jackpotcontribution.
If ‘includejackpotcontribution’ is true, this field is riskamt - (tie bet).
Net return of the bet to the player.
Note:
Decimal
winloss If ‘includejackpotcontribution’ is false, this field is winamt + (riskamt +
Precision: 6 places
jackpotcontribution).
If ‘includejackpotcontribution’ is true, this field is winamt + riskamt.

Winning amount of the bet. The value is positive when a win is credited to the Decimal
winamt
player’s account, or zero if no win occurs. Precision: 6 places
Decimal
loss Summarized amount of rounds with negative winloss.
Precision: 6 places
String
userid Unique identifier of the player.
Max length: 50

Example Calls:
Request

GET
/api/history/bets/players/total?startdate=2017-04-05T01%3A05%3A01%2B08%3A00&enddate=2017-04-05T02%3A05%3A0
1%2B08%3A00 HTTP/1.1
Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer MqtZWhfDu6tCKzDjE2tjEkjFYJylBaYoZO4vlUqATP4HeUas8hDI1pJp4oakZdxsp
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
username,turnover,validbet,winloss,winamt,userid
operatortestuser21,40.000000,40.000000,20.000000,60.000000,operator21

JSON:
[
{
"username": "operatortestuser21",
"turnover": 40,
"validbet": 40,
"winloss": 20,
"winamt": 60,
"userid": "operator21"
}
]

Failed result:
See 3.3 Error Handling

7.6.11 Reward History

Back to Function List

KINGMAKER - Operator API Integration Guide v1.25

 40

The method is used to get players’ rewards for a specified tournament date/time range.

URL: https://<KMAPIServerURL>/api/history/rewards
HTTP method: GET
HTTP header: X-QM-Accept(optional): csv(default) or json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Definition Required (Y/N) Type

Starting date of the tournament.

Date (ISO 8601)
startdate URL-encode it before sending out the request. Y
Length: 25
e.g., 2014-09-25T00:00:00+00:00

Ending date of the tournament.

‘enddate’ must not be more than 90 days past the ‘startdate’. Date (ISO 8601)
enddate Y
URL-encode it before sending out the request. Length: 25
e.g., 2014-09-25T01:01:00+00:00

Return Parameters:
Parameter Definition Type

GUID
rewardid Unique identifier of the reward.
Max length: 36
String
userid Unique identifier of the player.
Max length: 50
Decimal
amt Amount of the reward.
Precision: 6 places
String (ISO 4217)
cur Currency that the player is using in the KM system. See Appendix E
Length: 3

Example Calls:
Request

GET
/api/history/rewards?startdate=2017-04-05T01%3A05%3A01%2B08%3A00&enddate=2017-04-05T02%3A05%3A01%2B08%
3A00 HTTP/1.1
Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer MqtZWhfDu6tCKzDjE2tjEkjFYJylBaYoZO4vlUqATP4HeUas8hDI1pJp4oakZdxsp
X-QM-Accept: csv(default) or json

Response

Successful result:

CSV:
rewardid,userid,amt.cur
b3cb943a-c478-421b-b75c-46ce5e9f9241,02_REAL_mmk_en-us,1000,MMK

KINGMAKER - Operator API Integration Guide v1.25

 41

5ca5f0bf-182f-4061-82c8-72436f950124,03_REAL_mmk_en-us,5000,MMK

JSON:
[
{
"rewardid": "b3cb943a-c478-421b-b75c-46ce5e9f9241",
"userid": "02_REAL_mmk_en-us",
"amt": 1000,
"cur": "MMK"
},
{
"rewardid": "5ca5f0bf-182f-4061-82c8-72436f950124",
"userid": "03_REAL_mmk_en-us",
"amt": 5000,
"cur": "MMK"
}
]

Failed result:
See 3.3 Error Handling

KINGMAKER - Operator API Integration Guide v1.25

 42

8. Single Wallet Integration

Back to Function List

Operators may wish to implement the Single Wallet API interface, which enables the UGS system to pass
transactions from the Game Providers to the Operator with no intermediate wallet. This is also known as a
“Common Wallet” integration.

Note: this integration method requires that the Operator implements the API methods described in this section.

This implementation that the operator implements will be referred to as the Operator Single Wallet API Server, or
simply “the Operator API Server”.

The UGS Single Wallet Client that calls the API will be referred to as the UGS Single Wallet API Client, or simply “the
UGS API Client”.

8.1 Sequence Diagram

8.2 Client-Server Authorization

Custom HTTP headers are required when sending requests to the Operator API server. The said headers are used to
verify that KM is authorized to communicate with the Operator API server. Below are the headers needed.

Name Definition

X-QM-ClientId The unique ID for KM , provided at setup time by the Operator.

X-QM-ClientSecret The shared secret key, provided at setup time by the Operator.

KINGMAKER - Operator API Integration Guide v1.25

 43

Note: The following is kept only for operators who still use OAuth integration, however, it’s recommended to
migrate to the new authentication mechanism mentioned above, which means Authorization Bearer header is
not needed anymore.

OAuth2 authorization must be implemented by the Operator API Server, which is used to verify that the UGS API
Client is authorized to communicate with it.

In order to implement the OAuth 2.0 standard, an Access Token is generated based upon a shared Client ID and
Client Secret, provided to the Operator at setup time. The Access Token is then used as the Bearer value of the
Authorization HTTP Header for all subsequent server API requests.

The default timeout of the token will be 1 hour, at which time it must be refreshed to make further API calls.

URL: http(s)://<OperatorAPIServerCallbackURL>/wallet/token
HTTP method: POST
HTTP header: Content-Type: application/x-www-form-urlencoded

Method Parameters:
Parameter Definition Required (Y/N) Type

The unique ID for KM , provided at setup time by the String

client_id Y
Operator Max length: 50

The shared secret key, provided at setup time by the String

client_secret Y
Operator Max length: 50

grant_type Always “client_credentials” Y String

scope Always “wallet” Y String

Return Parameters:
Parameter Definition Required (Y/N) Type

The access token used to secure calls to the Operator’s String

access_token Y
API server. Max length: 255

token_type Always “bearer” Y String

expires_in Timeout in seconds, will be 3600 (1 hour) Y Integer

scope Always “wallet” Y String

Error Parameters:
Parameter Definition Required (Y/N) Type

error Error code. N String

error_description Description of error. N String

Example Calls:
Request

KINGMAKER - Operator API Integration Guide v1.25

 44

POST /wallet/token
Header: Content-Type: application/x-www-form-urlencoded
Content:grant_type=client_credentials&scope=wallet&client_id=Single-Wallet-Integration&client_secret=1uuvtpXapvS6Rws
lyA2FgrZQA7V5EoPNT8djr0o8wqf1

Response

Successful result:
{
"access_token": "JXhHKcdt3rELh0GqPY0PCrH4NgZwBxhxPsucdZuTanlAfZfOKYnmBHaY6atcks0R2",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "wallet"
}

Failed result:
{
"error": "invalid_scope",
"error_description": "Invalid Scope"
}

For OAuth error codes, see Appendix A.

8.3 Debit
Back to Function List

Once the UGS API Client is authenticated, it may conduct a Debit action with the Operator API Server, to take funds
from the Player wallet. This method will require that the OAuth token is provided in the header, as per the OAuth
standard.

Note
1. There could be multiple transactions in this request (see ‘transactions’ parameter below), and when txtype=500
(placebet), the parameter ‘transactional’ will be true, which means these transactions should be all successful or
all failed.

URL: http(s)://<OperatorAPIServerCallbackURL>/wallet/debit
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {The unique ID for KM }
HTTP header: X-QM-ClientSecret: {The shared secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Description Type

testmode accepts: String

(optional) delay-10 will simulate slow request (10 seconds delay) Max length: 100
delay-5 will simulate slow request (5 seconds delay)
fail-500 will simulate 500 error response
emptyresponse will return empty response

transactional true means transactions in this request should be all successful or all failed. Boolean
false means transactions can be successful individually. (true or false)

KINGMAKER - Operator API Integration Guide v1.25

 45

transactions Object array container for fields below. Array

Depending on different types of games, there could be one or multiple
transactions in this array; for example: one player can place multiple bets in a
round of live dealer baccarat.
userid String
Unique identifier of the player
Max length: 50
authtoken String
Player token if exists
Max length: 2000
brandcode String
Unique code identifying the brand
Max length: 20
amt Amount of transaction. Must be equal to or greater than 0. When cancelling a Decimal
lose bet, the amount is 0 with txtype 560. Precision: 6 places
cur String
Currency of the transaction, using the currency code configured for the Brand
Length: 3-8
ipaddress String
Player client IP address
(optional) Max length: 40

UGS Platform identifier of the unique action. May not be repeated. If a GUID
ptxid duplicate id is sent, the previous result is re-sent with a the Duplicate flag. This Max length: 36
corresponds to the UGS GameActionId.

If assigned a value, it points to a UGS Platform transaction identifier. GUID

For example, when 'txtype' is 560 (cancel transaction), the value of 'refptxid' Max length: 36
refptxid will be the target transaction for canceling.

This field may have a value when txtype is 510, 520, 530, 540, and 560.

txtype The type of the transaction, listed in Appendix F. Integer

Date (ISO)
Timestamp that UGS processed the action.
timestamp Length: 25
e.g. 2014-09-25T07:07:31+00:00

platformtype The platform the player comes from. See Appendix L for all values. Integer

String
gpcode Game Provider unique code
Max length: 50

String
gamecode UGS Game unique code
Max length: 50

String
gamename UGS short name of the game
Max length: 50

gametype The type of the game (0=Slot, 1=TableGame, etc), listed in Appendix H. Integer

String
externalgameid Game Provider unique game id
Max length: 50

Unique UGS identifier of the round or hand, or draw. A round joins a group of GUID
roundid
bets together. Max length: 36

String
externalroundid Unique Game Provider identifier of the round or hand, or draw.
Max length: 64

betid UGS identifier of the bet GUID

(optional) (Return null if txtype is 590) Max length: 36

KINGMAKER - Operator API Integration Guide v1.25

 46

externalbetid Game Provider identifier of the bet. Is not consistently provided by game String
(optional) providers. Max length: 50

Timestamp that UGS processed the action. Date (ISO)

senton
e.g. 2014-09-25T07:07:31+00:00 Length: 25

Boolean
isclosinground Flag to indicate whether this action closes the round
(true or false)

Gross Gaming Revenue contribution created by this event. This value can be Decimal
ggr
negative. Precision: 6 places

Turnover contribution created by this event, which equals to valid bet in this Decimal
turnover
method. It won't be negative value. Precision: 6 places

unsettledbets Unsettled bets contribution created by this event. It's an adjustment value, Decimal
not a running total, and it can be negative values. Operators can simply ignore Precision: 6 places
this if not needed.

isbuyingame true means this transaction is from an In-Game Fund Transfer game at Boolean
Appendix M. (true or false)

false means this transaction is from a normal game.

Please refer to Question #7 in Section 8.10 for how to properly handle the
transaction.

walletcode String
Optional parameter designating which wallet to use on the operator side
(optional) Max length: 20

bonustype Indicates that the bonus type that originated from the game action, listed in Integer
(optional) Appendix G.

bonuscode String
Indicates the bonus campaign that originated from the game action.
(optional) Max length: 50

desc Extended description passed from Game Provider. Bet Type could be stored in String
(optional) this field, e.g. “BaBank”, “BaPlayer”... etc. Max length: 2000

commission The commission amount from player for this round, only appear when the Decimal
(optional) game type is card game Precision: 6 places

Return Parameters:
Parameter Description Type

err Error code (900). Not present if no error occurs.

This top-level error means an error with the entire request, and that
everything failed, i.e. parameter ‘transactions’ (shown below) should be an
Integer
empty array.

If some transactions are successful and some are failed, those individual errors
should be returned in the ‘transactions’ node, and this top-level error should
not present.

errdesc English description of error. Not present if no error occurs. String

transactions Object array container for fields below. Array

KINGMAKER - Operator API Integration Guide v1.25

 47

txid Operator transaction identifier of the unique action. String

Max length: 50

ptxid UGS Platform transaction identifier of the unique action provided in the GUID
request. Length: 36

bal Amount of the player balance after the transaction is complete. Decimal
Precision: 6 places

cur Currency of the player, using the currency code configured for the Brand String
Length: 3-8

dup Duplicate flag indicating whether this is a re-sent result. Note: the bal field Boolean
should contain the current balance if the result is re-sent. (true or false)

err Error code.

Integer
Not present if no error occurs.

errdesc Description of error. String

Not present if no error occurs.

Example Calls:
Request

POST /wallet/debit HTTP/1.1

Content-Type: application/json
Accept: application/json
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer pM8ZEKjbnk5kC7RqvdBn1gcZRfC8ccVxBbQmbIZYnVYEb4LirxfS9XARFvPJa0KjM

{
"transactional": “true”,
"transactions": [
{
"userid": "bob123",
"authtoken":"j9rlVRbwRsKG0pE2l55fn8Cw5TF2guj81tSr…(trimmed)",
"brandcode": "brandABC",
"amt": 50,
"cur": "THB",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"refptxid": null,
"txtype" : 500,
"timestamp": "2015-11-26T07:16:03+00:00",
"platformtype": 0,
"gpcode": "KMQM",
"gamecode": "thai_hi_lo2",
"gamename": "Thai Hi Lo 2",
"gametype": 1,
"externalgameid": "thai-hi-lo-2",
"roundid": "56677849-fb7b-49b8-ad1b-b393c54c01cf",
"externalroundid": "28849c84-fb7b-49b8-ad1b-b393c54c01cf",
"betid": "28849c84-fb7b-49b8-ad1b-b393c54c01cf",
"senton": "2015-11-26T07:16:01+08:00",
"isclosinground": "false",
"ggr": 0,
"turnover": 50,

KINGMAKER - Operator API Integration Guide v1.25

 48

"unsettledbets": 50,
"walletcode": "TableGameWallet",
"desc": "",
“commission”:”1.000000”
}
]
}

Response
Successful result:
{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"bal": 206.5,
"cur": "THB",
"dup": false
}
]
}

Successful result with duplicate transactions:

{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"dup": true
}
]
}

Failed result:
{
"err": 10,
"errdesc": "Token has expired"
}

KINGMAKER - Operator API Integration Guide v1.25

 49

8.4 Credit
Back to Function List

Once the UGS API Client is authenticated, it may conduct a Credit action with the Operator API Server. This method
will require that the OAuth token is provided in the header, as per the OAuth standard.

URL: http(s)://<OperatorAPIServerCallbackURL>/wallet/credit
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {The unique ID for KM }
HTTP header: X-QM-ClientSecret: {The shared secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Description Type

testmode accepts: String

(optional) delay-10 will simulate slow request (10 seconds delay)
delay-5 will simulate slow request (5 seconds delay)
fail-500 will simulate 500 error response
emptyresponse will return empty response

transactions Object array container for fields below. Array

Note: there could be one or more transactions in this array, these transactions can
be successful or failed individually (see Return Parameters below for details).

String
userid Unique identifier of the player
Max length: 50
String
authtoken Player token if exists.
Max length: 2000
String
brandcode Unique code identifying the brand
Max length: 20
Amount of transaction. May be 0 or greater Decimal
6 decimal precision
amt
If txtype is 511 and redeemocode has value , this amount will be 0.
That means this Jackpot win transaction should be credited manually
String
cur Currency of the transaction, using the currency code configured for the Brand
Length: 3-8
ipaddress String
Player client IP address.
(optional) Max length: 40
ptxid UGS Platform identifier of the unique action. May not be repeated. If a duplicate id GUID
is sent, the previous result is re-sent with the Duplicate flag. This corresponds to Max length: 36
the UGS GameActionId.

refptxid If assigned a value, it points to a UGS Platform transaction identifier. GUID

For example, when 'txtype' is 560 (cancel transaction), the value of 'refptxid' will be Max length: 36
the target transaction for canceling.
This field may have a value when txtype is 510, 520, 530, 540, and 560.

Note: for txtype 530 (Free bet), this value may refer to another closed round and
this free bet request could be a new round; please pay attention and handle this
possible situation.

KINGMAKER - Operator API Integration Guide v1.25

 50

txtype The type of the transaction, listed in Appendix F. Integer

timestamp Timestamp that UGS processed the action. Date (ISO)
e.g. 2014-09-25T07:07:31+00:00 Length: 25
platformtype The platform the player comes from. Integer
See Appendix L - Platform Types for all values.
String
gpcode Game Provider unique code
Max length: 50
String
gamecode UGS Game unique code
Max length: 50
String
gamename UGS short name of the game
Max length: 50
gametype The type of the game (0=Slot, 1=TableGame, etc), listed in Appendix H. Integer
String
externalgameid Game Provider unique game id
Max length: 50
Unique UGS identifier of the round or hand, or draw. A round joins a group of bets GUID
roundid
together. Max length: 36
String
externalroundid Unique Game Provider identifier of the round or hand, or draw.
Max length: 64
betid UGS identifier of the bet GUID
(optional) (Return null if txtype is 590) Max length: 36
externalbetid Game Provider identifier of the bet. Is not consistently provided by game providers. String
(optional) Max length: 64
Timestamp that UGS processed the action. Date (ISO)
senton
e.g. 2014-09-25T07:07:31+00:00 Length: 25
Boolean
isclosinground Flag to indicate whether this action closes the round.
(true or false)
Gross Gaming Revenue contribution created by this event. This value can be Decimal
ggr
negative. Precision: 6 places
Turnover contribution created by this event, which equals to valid bet in this Decimal
turnover
method. It won't be negative value. Precision: 6 places
unsettledbets Unsettled bets contribution created by this event. It's an adjustment value, not a Decimal
running total, and it can be a negative value. Operators can simply ignore this if not Precision: 6 places
needed.

isbuyingame true means this transaction is from an In-Game Fund Transfer game at Appendix Boolean
M. (true or false)

false means this transaction is from a normal game.

Please refer to Question #7 in Section 8.10 for how to properly handle the
transaction.

walletcode Optional parameter designating which wallet to use on the operator side String
(optional) Max length: 20
bonustype Indicates that the bonus type that originated from the game action, listed in Integer
(optional) Appendix G.
bonuscode Indicates the bonus campaign that originated from the game action . String
(optional) Max length: 50
desc Extended description passed from Game Provider. String
(optional) Max length: 2000

KINGMAKER - Operator API Integration Guide v1.25

 51

jpexternalid Indicates jackpot hit pool id String

(optional) Note: only sent with txtype =511 (win jackpot) Max length: 255

jpcur Currency of the jackpot hit String

(optional) Note: only sent with txtype =511 (win jackpot) Length: 3-8

jprate Exchange rate of jackpot hit amount Decimal

(optional) Note: only sent with txtype =511 (win jackpot) Precision: 3 places

jpamt Player jackpot hit amount Decimal

(optional) Note: only sent with txtype =511 (win jackpot) Precision: 6 places

jpcvtamt Player jackpot hit amount that converted by rate Decimal

(optional) Note: only sent with txtype =511 (win jackpot) Precision: 6 places

jpbal Jackpot pool remain balance Decimal

(optional) Note: only sent with txtype =511 (win jackpot) Precision: 2 places

jpcontribs Object array container for fields below. Array

(optional)
Indicates jackpot contribution data,it is different from the above jp hit data .
please see the sample request below

jpexternalid Indicates jackpot pool id String

Note: inside the jpcontribs array Max length: 255

jpcur Currency of the jackpot contribution String

Note: inside the jpcontribs array Length: 3-8

jprate Exchange rate of jackpot contribution amount Decimal

Note: inside the jpcontribs array Precision: 3 places

jpamt Player contribute to this Jackpot pool amount Decimal

Note: inside the jpcontribs array Precision: 6 places

jpcvtamt Player contribute to this Jackpot pool converted by rate amount Decimal
Note: inside the jpcontribs array Precision: 6 places

jpbal Jackpot pool remain balance Decimal

Note: inside the jpcontribs array Precision: 2 places

commission The commission amount from player playerd this round , only appear when game Decimal
(optional) type is card game Precision: 6 places

redeemcode This code is represented as the jackpot code to players who could request the String
(optional) jackpot win amount from the operator by using this code. Length: 14

Return Parameters:
Parameter Description Type

err Error code (900). Not present if no error occurs. Integer

This top-level error means an error with the entire request, and that everything
failed, i.e. parameter ‘transactions’ (shown below) should be an empty array.
If some transactions are successful and some are failed, those individual errors
should be returned in the ‘transactions’ node, and this top-level error should not
present.

errdesc Description of error. Not present if no error occurs. String

KINGMAKER - Operator API Integration Guide v1.25

 52

transactions Object array container for fields below. Array

Each transaction result is described with an element of this array, and they can be
succeeded or failed individually.

txid Operator transaction identifier of the unique action. String

Max length: 50

ptxid UGS Platform transaction identifier of the unique action provided in the request. GUID
Length: 36

bal Amount of the player balance after the transaction is complete. Decimal
Precision: 6 places

cur Currency of the player String

Length: 3-8

dup Duplicate flag indicating whether this is a re-sent result. Note: the bal field should Boolean
contain the current balance if the result is re-sent. (true or false)

err Error code. Not present if no error occurs. Integer

errdesc English description of error. Not present if no error occurs. String

Example Calls:
Request

POST /wallet/credit HTTP/1.1

Content-Type: application/json
Accept: application/json
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer pM8ZEKjbnk5kC7RqvdBn1gcZRfC8ccVxBbQmbIZYnVYEb4LirxfS9XARFvPJa0KjM

{
"transactions": [
{
"userid": "bob123",
"authtoken":"j9rlVRbwRsKG0pE2l55fn8Cw5TF2guj81tSr…(trimmed)",
"brandcode": "brandABC",
"amt": 50,
"cur": "THB",
"ipaddress": "127.0.0.1",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a123",
"refptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"txtype" : 540,
"timestamp": "2014-09-25T07:07:31+00:00",
"platformtype”: 0,
"gpcode": "KMQM",
"gamecode": "thai_hi_lo2",
"gamename": "Thai Hi Lo 2",
"gametype": 1,
"externalgameid": "thai-hi-lo-2",
"roundid": "56677849-fb7b-49b8-ad1b-b393c54c01cf",
"externalroundid": "28849c84-fb7b-49b8-ad1b-b393c54c01cf",
"betid": "28849c84-fb7b-49b8-ad1b-b393c54c01cf",
"senton": "2014-09-25T07:07:30+00:00",
"isclosinground": "false",
"ggr": 50,
"turnover": 50,

KINGMAKER - Operator API Integration Guide v1.25

 53

"unsettledbets": 0,
"walletcode": "TableGamerWallet",
“commission”:”1.000000”
}
]
}

Jackpot win sample request content (will include jackpot contribution):

{
"transactions":[
{
"userid":"01_REAL_thb_en-us",

"authtoken":"fICOmJpKYwLr7LXrEoVr9EfERMVmi8a0QcZDo6rJMhIZwksFex8l4sm2qULElVKIkdM4MboAkWb4PGvNaVVQ63d1s
E0EklUdEIiCcuqVWw7pa7VJvIzlR17CqKDDBEVobZ",
"brandcode":"PROXYBRAND1",
"txtype":510,
"cur":"THB",
"amt":15.0,
"ptxid":"7879124e-ac8b-e711-b323-7824af8296b8",
"refptxid":"7679124e-ac8b-e711-b323-7824af8296b8",
"timestamp":"2017-08-27T21:49:44-07:00",
"walletcode":null,
"ipaddress":"184.70.137.34",
"platformtype":0,
"gpcode":"KMQM",
"gamecode":"thai_hi_lo2",
"gamename":"Thai Hi Lo 2",
"gametype":1,
"externalgameid":"thai-hi-lo-2",
"roundid":"7479124e-ac8b-e711-b323-7824af8296b8",
"externalroundid":"20f0d11295b248159ba63b184f4d8d1e",
"betid":"c712bee0-5fb4-4afc-a028-6ad2af2ac707",
"externalbetid":"98c80938-4e71-4767-a57f-7e7303947615",
"senton":"2017-08-27T21:49:44-07:00",
"isclosinground":true,
"ggr":-5.00,
"turnover":10.00,
"unsettledbets":-10.000,
"bonustype":0,
"bonuscode":null,
"desc":null,
"jpcontribs":[
{
"jpexternalid":"QMTHBProgressivejackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":2.0,
"jpcvtamt":2.0,
"jpbal":2.0
},
{
"jpexternalid":"QMTHBCeilingjackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":3.0,
"jpcvtamt":3.0,
"jpbal":3.0
},

KINGMAKER - Operator API Integration Guide v1.25

 54

{
"jpexternalid":"QMTHBTimedjackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":5.0,
"jpcvtamt":5.0,
"jpbal":5.0
}
]
},
{
"userid":"01_REAL_thb_en-us",

"authtoken":"fICOmJpKYwLr7LXrEoVr9EfERMVmi8a0QcZDo6rJMhIZwksFex8l4sm2qULElVKIkdM4MboAkWb4PGvNaVVQ63d1s
E0EklUdEIiCcuqVWw7pa7VJvIzlR17CqKDDBEVobZ",
"brandcode":"PROXYBRAND1",
"txtype":511,
"cur":"THB",
"amt":1000.0,
"ptxid":"7b79124e-ac8b-e711-b323-7824af8296b8",
"refptxid":null,
"timestamp":"2017-08-27T13:49:44-07:00",
"walletcode":null,
"ipaddress":"184.70.137.34",
"platformtype":0,
"gpcode":"KMQM",
"gamecode":"thai_hi_lo2",
"gamename":"Thai Hi Lo 2",
"gametype":1,
"externalgameid":"thai-hi-lo-2",
"roundid":"7979124e-ac8b-e711-b323-7824af8296b8",
"externalroundid":"20f0d11295b248159ba63b184f4d8d1e_jackpot",
"betid":"5362af95-496b-40bd-b242-10aac6ffe2ee",
"externalbetid":"98c80938-4e71-4767-a57f-7e7303947615",
"senton":"2017-08-27T13:49:44-07:00",
"isclosinground":false,
"ggr":0.0,
"turnover":0.0,
"unsettledbets":0.0,
"bonustype":0,
"bonuscode":null,
"desc":"",
"jpexternalid":"QMTHBProgressivejackpot",
"jpcur":"THB",
"jpamt":1000.0,
"jpbal":10.0,
"jprate":1.0,
"jpcvtamt":1000.0
}
]
}
Jackpot win sample request content with redeemcode :
{
"transactions":[
{
"userid":"01_REAL_thb_en-us",

"authtoken":"fICOmJpKYwLr7LXrEoVr9EfERMVmi8a0QcZDo6rJMhIZwksFex8l4sm2qULElVKIkdM4MboAkWb4PGvNaVVQ63d1s
E0EklUdEIiCcuqVWw7pa7VJvIzlR17CqKDDBEVobZ",

KINGMAKER - Operator API Integration Guide v1.25

 55

"brandcode":"PROXYBRAND1",
"txtype":510,
"cur":"THB",
"amt":15.0,
"ptxid":"7879124e-ac8b-e711-b323-7824af8296b8",
"refptxid":"7679124e-ac8b-e711-b323-7824af8296b8",
"timestamp":"2017-08-27T21:49:44-07:00",
"walletcode":null,
"ipaddress":"184.70.137.34",
"platformtype":0,
"gpcode":"KMQM",
"gamecode":"thai_hi_lo2",
"gamename":"Thai Hi Lo 2",
"gametype":1,
"externalgameid":"thai-hi-lo-2",
"roundid":"7479124e-ac8b-e711-b323-7824af8296b8",
"externalroundid":"20f0d11295b248159ba63b184f4d8d1e",
"betid":"c712bee0-5fb4-4afc-a028-6ad2af2ac707",
"externalbetid":"98c80938-4e71-4767-a57f-7e7303947615",
"senton":"2017-08-27T21:49:44-07:00",
"isclosinground":true,
"ggr":-5.00,
"turnover":10.00,
"unsettledbets":-10.000,
"bonustype":0,
"bonuscode":null,
"desc":null,
"jpcontribs":[
{
"jpexternalid":"QMTHBProgressivejackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":2.0,
"jpcvtamt":2.0,
"jpbal":2.0
},
{
"jpexternalid":"QMTHBCeilingjackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":3.0,
"jpcvtamt":3.0,
"jpbal":3.0
},
{
"jpexternalid":"QMTHBTimedjackpot",
"jpcur":"THB",
"jprate":1.0,
"jpamt":5.0,
"jpcvtamt":5.0,
"jpbal":5.0
}
]
},
{
"userid":"01_REAL_thb_en-us",

"authtoken":"fICOmJpKYwLr7LXrEoVr9EfERMVmi8a0QcZDo6rJMhIZwksFex8l4sm2qULElVKIkdM4MboAkWb4PGvNaVVQ63d1s
E0EklUdEIiCcuqVWw7pa7VJvIzlR17CqKDDBEVobZ",
"brandcode":"PROXYBRAND1",

KINGMAKER - Operator API Integration Guide v1.25

 56

"txtype":511,
"cur":"THB",
"amt":0,
"ptxid":"7b79124e-ac8b-e711-b323-7824af8296b8",
"refptxid":null,
"timestamp":"2017-08-27T13:49:44-07:00",
"walletcode":null,
"ipaddress":"184.70.137.34",
"platformtype":0,
"gpcode":"KMQM",
"gamecode":"thai_hi_lo2",
"gamename":"Thai Hi Lo 2",
"gametype":1,
"externalgameid":"thai-hi-lo-2",
"roundid":"7979124e-ac8b-e711-b323-7824af8296b8",
"externalroundid":"20f0d11295b248159ba63b184f4d8d1e_jackpot",
"betid":"5362af95-496b-40bd-b242-10aac6ffe2ee",
"externalbetid":"98c80938-4e71-4767-a57f-7e7303947615",
"senton":"2017-08-27T13:49:44-07:00",
"isclosinground":false,
"ggr":0.0,
"turnover":0.0,
"unsettledbets":0.0,
"bonustype":0,
"bonuscode":null,
"desc":"",
"jpexternalid":"QMTHBProgressivejackpot",
"jpcur":"THB",
"jprate":1.0,
"Jpcvtamt":1000.0,
"jpamt":1000.0,
"jpbal":10.0,
"redeemcode":"20151234567890"
}
]
}

Response

Successful result:
{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a123",
"bal": 206.5,
"cur": "THB",
"dup": false
}
]
}

Successful result with duplicate transactions:

{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a123",
"dup": true

KINGMAKER - Operator API Integration Guide v1.25

 57

}
]
}

Successful result with individual failed transactions:

{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a123",
"bal": 206.5,
"cur": "THB",
"dup": false
},
{
"txid": "662675",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a124",
"err": 600,
"errdesc": "Transaction not exists",
}
]
}

Failed result (return error in the top-level node):

{
"err": 10,
"errdesc": "Token has expired"
}

KINGMAKER - Operator API Integration Guide v1.25

 58

8.5 Reward
Back to Function List

This method is used when the Operator joins tournaments and its players have won the rewards. Once the UGS API
Client is authenticated, it may conduct a Reward action with the Operator API Server, which will credit the player's
wallet. This method will require that the OAuth token is provided in the header, as per the OAuth standard.

URL: http(s)://<OperatorAPIServerCallbackURL>/wallet/reward
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {The unique ID for KM }
HTTP header: X-QM-ClientSecret: {The shared secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Description Type

brandcode Unique code identifying the brand String

Max length: 20

transactions Object array container for fields below. Array

Note: there could be one or more transactions in this array, these transactions can
be successful or failed individually (see Return Parameters below for details).

String
userid Unique identifier of the player
Max length: 50
Decimal
amt Amount of transaction. Must be greater than 0
6 decimal precision
String
cur Currency of the transaction, using the currency code configured for the Brand
Length: 3-8
ptxid UGS Platform identifier of the unique action. May not be repeated. If a duplicate id GUID
is sent, the previous result is re-sent with the Duplicate flag. Max length: 36

desc Description of the reward. String

(optional) Max length: 256

Return Parameters:
Parameter Description Type

err Error code (900). Not present if no error occurs. Integer

This top-level error means an error with the entire request, and that everything
failed, i.e. parameter ‘transactions’ (shown below) should be an empty array.
If some transactions are successful and some are failed, those individual errors
should be returned in the ‘transactions’ node, and this top-level error should not be
present.

errdesc Description of error. Not present if no error occurs. String

KINGMAKER - Operator API Integration Guide v1.25

 59

transactions Object array container for fields below. Array

Each transaction result is described with an element of this array, and they can be
succeeded or failed individually.

txid Operator transaction identifier of the unique action. String

Max length: 50

ptxid UGS Platform transaction identifier of the unique action provided in the request. GUID
Length: 36

bal Amount of the player balance after the transaction is complete. Decimal
Precision: 6 places

cur Currency of the player String

Length: 3-8

dup Duplicate flag indicating whether this is a re-sent result. Note: the bal field should Boolean
contain the current balance if the result is re-sent. (true or false)

err Error code. Not present if no error occurs. Integer

errdesc English description of error. Not present if no error occurs. String

Example Calls:
Request

POST /wallet/reward HTTP/1.1

Content-Type: application/json
Accept: application/json
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer pM8ZEKjbnk5kC7RqvdBn1gcZRfC8ccVxBbQmbIZYnVYEb4LirxfS9XARFvPJa0KjM

{
"brandcode": “brandABC”,
"transactions": [
{
"userid": "bob",
"amt": 700,
"cur": "THB",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"desc": "Reward type: 0"
},
{
"userid": "john",
"amt": 500,
"cur": "THB",
"ptxid": "5d099a99-6fa8-4ed5-846a-02d715fa3866",
"desc": "Reward type: 0"
}
]
}

Response

Successful result:
{

KINGMAKER - Operator API Integration Guide v1.25

 60

"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"bal": 906.5,
"cur": "THB",
"dup": false
},
{
"txid": "662675",
"ptxid": "5d099a99-6fa8-4ed5-846a-02d715fa3866",
"bal": 591,
"cur": "THB",
"dup": false
}
]
}

Successful result with duplicate transactions:

{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"bal": 906.5,
"cur": "THB",
"dup": true
},
{
"txid": "662675",
"ptxid": "5d099a99-6fa8-4ed5-846a-02d715fa3866",
"bal": 591,
"cur": "THB",
"dup": true
}
]
}

Successful result with individual failed transactions:

{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"bal": 906.5,
"cur": "THB",
"dup": false
},
{
"ptxid": "5d099a99-6fa8-4ed5-846a-02d715fa3866",
"err": 300,
"errdesc": "Player not found",
}
]
}

Failed result (return error in the top-level node):

{
"err": 900,
"errdesc": "system error"

KINGMAKER - Operator API Integration Guide v1.25

 61

8.6 Get Balance

Back to Function List

Once the UGS API Client is authenticated, it may conduct a GetBalance action with the Operator API Server, which
will return the balance of one or many player’s wallet. This method will require that the OAuth token is provided in
the header, as per the OAuth standard.

URL: http(s)://<OperatorAPIServerCallbackURL>/wallet/balance
HTTP method: POST
HTTP header: Content-Type: application/json
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {The unique ID for KM }
HTTP header: X-QM-ClientSecret: {The shared secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Description Type

testmode accepts: String

(optional) delay-10 will simulate slow request (10 seconds delay)
delay-5 will simulate slow request (5 seconds delay)
fail-500 will simulate 500 error response
emptyresponse will return empty response
setbalance:1000 will deposit 1000 in test env. only

users Object array container for fields below. There could be one or more users in this Array
array, and if Operator didn’t find a userid, then simply ignore it and no need to
return information for that player (and no error for that player).

authtoken The player token if exists. String

(optional) Note: Some game providers didn’t provide players tokens when they send a Max length: 2000
batch request to UGS to get multiple players’ balance, so this field may be null.

userid Unique identifier of the player from the brand specified with 'brandcode' String
parameter.. Max length: 50

brandcode Unique code identifying the brand. String

Max length: 20

lang Language code used by the player. If the language code is empty or does not String
(optional) present, or it is not supported at your end, please use player’s default language. Length: 5
See Appendix D for the list of language codes.

cur Currency of the transaction, using the currency code configured for the Brand String
Length: 3-8

KINGMAKER - Operator API Integration Guide v1.25

 62

walletcode Optional parameter designating which wallet to use on the operator side String
(optional) Note: If not present, please return all wallets of the specified ‘userid’. Max length: 20

Return Parameters:
Parameter Description Type

err Error code.Not present if no error occurs. Integer

errdesc Description of error. Not present if no error occurs. String

users Object array container for fields below. Array

Note: If there is a ‘userid’ that does not exist at the operator’s end, simply ignore
that player (no need to put that player in this array.
Child object of users array.

userid Unique identifier of the player from the brand. The wallets of this user are String
stored in the ‘wallets’ array below. Max length: 50

err Error code if failed to return balance of this user. Not present if no error occurs. Integer
errdesc Description of error. Not present if no error occurs. String
wallets Object array that contains one or more wallets. Array
Child object of wallets array.

code Wallet code. Return “MainWallet” If there is no multiple wallet. String

Max length: 20

bal Amount of the player balance Decimal

Precision: 6 places
cur Currency of the player. String
Length: 3-8
name Localized string of wallet name. String
(optional) Max length: 50
desc Localized string of wallet description. String
(optional) Max length: 256

Example Call:
Request

POST /wallet/balance HTTP/1.1

Content-Type: application/json
Accept: application/json
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer pM8ZEKjbnk5kC7RqvdBn1gcZRfC8ccVxBbQmbIZYnVYEb4LirxfS9XARFvPJa0KjM

{
"users": [
{
"userid": "bob123",
"brandcode": "brandABC",
"cur": "THB",
"lang": "zh-CN",
"walletcode": "TableGameWallet"
},
{

KINGMAKER - Operator API Integration Guide v1.25

 63

"userid": "mary345",
"brandcode": "brandABC",
"cur": "THB",
"lang": "zh-CN",
"walletcode": "SlotWallet"
}
]
}

Response
Successful result:
{
"users": [{
"userid": "bob123",
"wallets": [{
"code": "TableGameWallet",
"bal": 206.5,
"cur": "THB",
"name": "Table Game wallet",
"desc": "錢包1"
},
{
"code": "SlotWallet",
"bal": 100,
"cur": "THB",
"name": "Slot wallet",
"desc": "錢包2"
]
}, {
"userid": "mary345",
"wallets": [{
"code": "SlotWallet",
"bal": 5506.5,
"cur": "THB",
"name": "Slot wallet",
"desc": "錢包3"
}]
}]
}

Failed result for failure of entire request :

{
"err": 10,
"errdesc": "Token has expired"
}

Failed result with individual player error:

{
"users":[
{
"userid":"bob123",
"wallets":[
{
"code":"TableGameWallet",
"bal":206.5,
"cur":"THB",
}

KINGMAKER - Operator API Integration Guide v1.25

 64

]
},
{
"userid":"abc123",
"err":50,
"errdesc":"Currency Mismatch"
}
]
}

8.7 Transaction Grouping

Back to Function List

Credit, Debit and Cancel operations can contain multiple transactions. This is in order to allow batch processing,
and also to indicate sets of transactions that must be processed atomically.

The following table indicates what grouping properties each operation supports.

Operation Transactional? Multi-player Multi-transaction Multi-round

Debit Y Y Y N

Credit N Y Y N
Cancel N N Y N

Field Definitions

Whether the operation supports “transactional” parameter, indicating the transactions must be all
Transactional?
successful or all failed as a group.
Does the operation support multiple players within the same request?
Multi-player Note: supporting multiple players doesn't mean it will always have multiple players. For example, Debit
operation with txtype=500 (bet placement) will not contain multiple players.
Multi-transaction Does the operation support multiple transactions within the same request?
Does the operation support transaction processing requests for different game rounds within the same
Multi-round
request?

KINGMAKER - Operator API Integration Guide v1.25

 65

8.8 Returning Error Responses

Back to Function List

When there is no error, the 'err' and 'errdesc' property should not exist in the response content, or 'err' should be
assigned as 0.

The Entire Operation Failed

When a response content has 'err' and 'errdesc' in the top-level node, UGS will treat it as a failed operation, which
means the actions/transaction in operation are all failed.

Example:
{
"err": 10,
"errdesc": "Token has expired"
}

Partial Failure
When an operation contains partial success and failure result, the top-level node should not contain 'err' and 'errdesc'
property. Instead, individual error will be described in the sub nodes.

Example 1: A wallet/credit response that contains two successful and one failed transaction. Note that duplicated
transaction is not an error.
{
"transactions": [
{
"txid": "662674",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a727",
"bal": 206.5,
"cur": "THB",
"dup": false
},
{
"txid": "662675",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a728",
"bal": 220.0,
"cur": "THB",
"dup": true
},
{
"txid": "662675",
"ptxid": "c6c2fcf9-4685-4a91-8f57-e5185655a729",
"err": 600,
"errdesc": "transaction not exist. refptxid=12345"
}
]
}
Example 2: A wallet/balance response that contains one successful wallet balance (userid 'bob123') and one error (userid
'abd123').
{
"users":[
{
"userid":"bob123",
"wallets":[

{
"code":"TableGameWallet",

KINGMAKER - Operator API Integration Guide v1.25

 66

"bal":206.5,
"cur":"THB",
}
]
},
{
"userid":"abc123"
"err":50,
"errdesc":"Currency Mismatch"
}
]
}

8.9 Errors and Retry Handling

Back to Function List

The UGS Single Wallet API Client handles Operator API Server errors in a manner designed to be resilient to failure,
and acts as a mediation proxy between the Game Provider and the Operator.

This section describes how UGS handles errors and retries. There are two categories of transactions; each one is
handled differently:

1) Bet Placement
In the case of Bet Placements that result in a Debit request (txtype=500), if the Operator's API Server fails due to a
non-deterministic error, the transaction request will be retried once by the UGS Client API.

A non-deterministic error is one in which there is no clear success or failure of the transaction, including
“900 - System Error”, or a network timeout.

If the immediate retry fails, UGS will report failure to the Game Provider, and then send a Cancel operation to the
operator to cancel the previous Debit request. The UGS Client API will attempt the Cancel operation up to 5 times,
after which it will be queued for manual intervention.

If the error is deterministic, such as “100 - Insufficient Funds”, then the Debit transaction will fail immediately, will
not be retried, and the failure is reported immediately back to the Game Provider.

For cases of Debit requests with txtype other than 500, the error handling and retry logic are same as Credit
request described below.

2) Settlement
Settlement requests (including Win, Tie, Cancel PlaceBet, FreeBet, Jackpot operations) are basically Credit
operations, but in some cancellation scenarios, Debit operations are used.

Settlement operations that fail will be retried once immediately by UGS. If that attempt fails again, a success result
will be returned to the Game Provider along with the expected balance after the operation. This optimistic
behaviour is to prevent blocking of play due to delayed settlements. As well, many Game Providers do not handle
settlement errors, so UGS provides this mechanism on their behalf.

KINGMAKER - Operator API Integration Guide v1.25

 67

During such an error condition, there could be discrepancy of balances between a game client and the operator.
However, the discrepancy will disappear once the failed operation completes and the updated balance is returned
to the game client. The discrepancy will display only -- the player’s balance with the operator is always used as the
point of transaction.

Such requests will be retried with the operator 5 times, after which it will be queued for manual intervention. Each
successive retry will take exponentially longer, in order to give the target system time to recover.

Operation Failure Summary

Operation Type

Bet Placement Settlement

Debit with PlaceBet (txtype=500) Credit with Win, Tie, Cancel Placement,
FreeBet, Jackpot
Debit with Cancel Settlement

Condition Non-deterministic Summary: Summary:

Error UGS will retry once immediately, and if A ‘success’ value will be returned to the
that retry still fails, failure is returned to Game Provider, and UGS will handle the
Error code: 900 Game Provider. UGS will then try to Cancel queueing and retry the request with the
the request with the Operator. operator.

Method: Method:

1. Upon failure, return failure to 1. Upon failure, return success to

Game Provider Game Provider, with estimated
2. Attempt Cancel action 5 times balance (previous balance +
3. If Cancel does not *succeed, it is operation amount)
queued for manual intervention. 2. Retry request 5 times
3. If action does not succeed, it is
The condition of succeed: operator return queued for manual intervention.
1. succeed: 0
2. transaction doesn’t exist:600 The condition of succeed: operator return
3. transaction already cancelled: 610 succeed: 0.

Deterministic Error Immediate Fail

(return error to Game Provider)

KINGMAKER - Operator API Integration Guide v1.25

 68

8.10 Use Case of Single Wallet Integration

Back to Function List

No. Questions Answers

1 What is Single wallet? The UGS system to pass transactions from the Game Providers to the Operator
with no intermediate wallet. This is also known as a “Common Wallet”
integration.

2 What information should be ● Endpoint: where we get the balance, credit/debit of your site
provided to KM for single wallet ● Client id: provided by operator
integration? ● Client secret: provided by operator

3 Does Debit/Credit support ● For debit request:

multiple players within one 1. When txtype=500 (Placebet), it does not support multiple players.
request? 2. For others txtype except txtype=500, can support multiple players
● For credit request:
It supports multiple players within one request.

4 Does one request include two or In Slots game, it will not happen.
more transactions? In Live Dealer game (e.g. Baccarat/Roulette), it will happen.
(for bet placement)
Example scenarios:
1. If player places 2 bets and presses confirm button, we will receive one
request containing 2 transactions.
2. If player places 1 bet and presses confirm button, then places another
bet and presses confirm again, we will receive two requests.

5 While there is a request with No, transactions will be failed or successful individually. Only Place Bet
txtype = [any types other than (txtype=500) requires atomic operation.
500], if one transaction is failed,
would entire request fail?

6 How does KM cancel bets? Cancel Transaction (txtype=560) is a request initiated by Game Providers, and
can be used to cancel a previously successful bet placement. If Game Provider
cancels bet placement, KM will call wallet/credit + txtype 560

7 How should Operator handle For certain games, players may lose more than they place. Therefore, different
games that have in-game fund bet placement and settlement processes need to be handled by Operator and
transfer? Operator should also support fund transfer in order for players to play games.
These games (See Appendix M) have in-game fund transfer and different
transaction types (600, 610 and 611. See Appendix F) should be used by
Operator to handle the requests properly.

Here’s an example of how Operator should handle the process given that a
player places a bet of 10 THB and loses 10 THB in a round. The API requests will
be sent to Operator as follows.

1. /wallet/debit

txtype=610, amt=50, cur=THB

This is to inform Operator to deduct the player’s wallet beforehand as the player
may lose at most 50 THB in the round, which is more than its placement (10
THB)

2. /wallet/debit

KINGMAKER - Operator API Integration Guide v1.25

 69

txtype=500, amt=10, cur=THB

This is to inform Operator that the player’s real bet amount is 10 THB in the
round, and DO NOT deduct the player’s wallet since you had deducted the
amount in the previous debit request (/wallet/debit).

3. /wallet/credit

txtype=520, amt=0, cur=THB

txtype=600, amt=40, cur=THB

This is to inform Operator that the player loses the round and the system returns
40 THB to the player, meaning Operator should top up the player’s wallet with
40 THB.

To summarize:

1. Deduct/top up players’ wallet ONLY when the transaction type is 6xx.

2. DO NOT update players’ wallet when the transaction type is 5xx.
Record only the data itself.

Operator can use externalroundid to correlate all the requests in the same
round.

KINGMAKER - Operator API Integration Guide v1.25

 70

9. Direct Game Launch

Back to Function List

UGS provides a feature called Direct Game Launch, which consists of two components: a Game List API, and a
Game Launcher. This section describes how an Operator launches games directly without going through KM Lobby.

Prerequisites:

● In UGS BO, create a brand that belongs to an Operator (Licensee).

● In UGS BO, create a lobby for this brand, and add games to this lobby.

The following steps are involved for Operator to launch a game.

1. Operator gets an access token. See Section 5.1.

2. Operator gets its games by calling UGS Game List API. See Section 9.1.
3. Operator shows the games returned from Game List API on its own lobby.
4. Operator gets a player token. See Section 6.3.
5. Operator launches a game using Game Launcher with required parameters. See Section 9.2.

9.1 Game List

The Game List method is used to get a list of games for a specific brand.

URL: https://<KMAPIServerURL>/api/games
HTTP method: GET
HTTP header: Accept: application/json
HTTP header: X-QM-ClientId: {Operator's unique ID}
HTTP header: X-QM-ClientSecret: {Operator's secret key}
HTTP header: Authorization: Bearer {access token} (Unneeded if X-QM-ClientId and X-QM-ClientSecret are
provided)

Method Parameters:
Parameter Description Required (Y/N) Type

String (ISO 639-1

Language code used to return the localization of game name and
lang Y and ISO 3166-1)
description. See Appendix D
Length: 5

platformtype The platform the player comes from. See Appendix L Y Integer

Return Parameters:
Parameter Description Type

iconres Game icon resolutions supported by KM . Array of String

games Object array container for fields below. Array of Object

String
externalid Unique identifier of the game from Game Provider.
Max length: 50

String
code Game code.
Max length: 50

KINGMAKER - Operator API Integration Guide v1.25

 71

String
name Localized game name.
Max length: 50

String
description Localized game description.
Max length: 2048

String
providercode Game provider code, e.g., "KMQM". See Appendix K
Max length: 50

true/false representing status of the game. If the game or its game provider is put into Boolean
isactive
maintenance, the value is false, otherwise, true. (true or false)

type Game type. See Appendix H Integer

iconurl NOT AVAILABLE. Please get game icons from our support team. null

supportdemo true/false representing whether the game supports demo mode. If the game does, the Boolean
url value is true, otherwise, false. (true or false)

Object array container for fields below.

betlimits The value is null if the game is not a Live Dealer game or authtoken is not specified in Array of Object
the request.

String
id Bet limit ID from Game Provider. Used to launch a Live Dealer game.
Max length: 50

min Minimum bet amount. Integer

max Maximum bet amount. Integer

Example Calls:
Request

GET /api/games?lang=en-US&platformtype=0 HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer K5ML65OcQAStYHtTLY2dArzwGmNbkY2E3EMKgS6sbWTlN2v0cC073BmTE9p
Accept: application/json

Response

Successful result:
{
"iconres": [
"343x200",
"520x520"
],
"games": [
{
"externalid": "thai-hi-lo-2",
"code": "thai_hi_lo2",
"name": "Thai Hi Lo 2",
"description": "Thai Hi-Lo is a Thailand version of high or low (Hi-Lo), that is played with three dice in a shaker.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,

KINGMAKER - Operator API Integration Guide v1.25

 72

"supportdemourl": false
},
{
"externalid": "dragon-tiger-2",
"code": "dragon_tiger2",
"name": "Dragon Tiger 2",
"description": "Dragon Tiger is a very simple card game. The dealer will draw two cards, one for the dragon and one for
the tiger.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,
"supportdemourl": true
}
]
}

Failed result:
{
"err": 12,
"errdesc": "Token has expired"
}

KINGMAKER - Operator API Integration Guide v1.25

 73

9.2 Game Launcher

Back to Function List

The Game Launcher is used for Operator to launch games. Operator can build a Game Launch URL for each game,
and use it to launch a specific game.

URL: https://<KMLobbyServerURL>/gamelauncher
HTTP method: GET

Method Parameters:
Parameter Definition Required (Y/N) Type
String
gpcode Game provider code, e.g., "KMQM". See Appendix K Y
Max length: 50
String
gcode Game code. Y
Max length: 50
String
token Player token used to launch the game. Y
Max length: 2000
Language code can be used by player. See Appendix D String
lang N
It is able to change other languages with this parameter. Max length: 50

Example URLs:
https://staging-lobby.queenmakergames.co/gamelauncher?gpcode=KMQM&gcode=thai_hi_lo_2&token=1TbGFBdezVduidEfz
P98QZ78ZCY63bOZLxqaPE5x4u2MwPSwhfKOLE8QuCCpQQ7a4s1IIAJhDGo6MvOj57CoXEzI5Q78ruFFxkP7CwBzY1MJ83nrmFSm
O5VkGIBxLjnbEo

KINGMAKER - Operator API Integration Guide v1.25

 74

9.3 Launch Games

Here is a complete example that shows each step to a table game, including

1. Generate a brand access token. (please ignore this step if you are new integration)
2. Generate a player token (authorize a player).
3. Get a game list from Game List API.
4. Launch the game using Game Launcher.

1) Generate a brand access token (please ignore this step if you are new integration)

REQUEST:
POST /api/oauth/token HTTP/1.1
Host: staging-api.queenmakergames.co
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=playerapi&client_id=Operator-Integration&client_secret=1uuvtpXapvS6RwslyA2FgrZQA
7V5EoPNT8djr0o8wqf1

RESPONSE:
{
"access_token": "wgwPwspacMCOs8ODUAUx8thZYvV0krkgKZCYeWZGdmi7pPEgxbbMLzrWFzHuQPqy2",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "playerapi"
}
2) Generate a player token
REQUEST:
POST /api/player/authorize HTTP/1.1
Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer wgwPwspacMCOs8ODUAUx8thZYvV0krkgKZCYeWZGdmi7pPEgxbbMLzrWFzHuQPqy2
Content-Type: application/json
Accept: application/json

{
"ipaddress": "123.123.123.1",
"username": "frank enstein",
"userid": "frankenstein",
"lang": "zh-CN",
"cur": "THB",
"betlimitid": 1,
"istestplayer": true,
"platformtype": 0
}

RESPONSE:
{
"authtoken":"TPvYxzEysPgHs81Edhj71TTQrnETLWvzZwcU9jkCK0wChhObZyftcPGHyNZCzbwFFp6t2Mc380pCbHi11FgrAEpLSFHu
kNd8BwubpEBCc5Pnrrmicf21iCJhzjmKIEMkEU",
"isnew":true
}

KINGMAKER - Operator API Integration Guide v1.25

 75

3) Get a game list from Game List API

REQUEST:
GET /api/games?lang=en-US&platformtype=0 HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer wgwPwspacMCOs8ODUAUx8thZYvV0krkgKZCYeWZGdmi7pPEgxbbMLzrWFzHuQPqy2
Accept: application/json

RESPONSE:
{
"iconres": [
"343x200",
"520x520"
],
"games": [
{
"externalid": "thai-hi-lo-2",
"code": "thai_hi_lo_2",
"name": "Thai Hi Lo 2",
"description": "Thai Hi-Lo is a Thailand version of high or low (Hi-Lo), that is played with three dice in a shaker.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,
"supportdemourl": true
},

{
"externalid": "dragon-tiger-2",
"code": "dragon_tiger2",
"name": "Dragon Tiger 2",
"description": "Dragon Tiger is a very simple card game. The dealer will draw two cards, one for the dragon and one for the
tiger.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,
"supportdemourl": true
}
]
}

4) Launch the game using Game Launcher

Based on the information from previous steps, to launch KingMaker KM game "Thai Hi Lo 2", the Game Launcher URL is

https://staging-lobby.queenmakergames.co/gamelauncher?gpcode=KMQM&gcode=thai_hi_lo_2&token=TPvYxzEysPgHs81Ed
hj71TTQrnETLWvzZwcU9jkCK0wChhObZyftcPGHyNZCzbwFFp6t2Mc380pCbHi11FgrAEpLSFHukNd8BwubpEBCc5Pnrrmicf21iCJh
zjmKIEMkEU

KINGMAKER - Operator API Integration Guide v1.25

 76

9.4 Direct Bet History (Obsolete)

Note: This API is no longer supported.

9.5 Demo Game Launcher

Back to Function List

The Demo Play Launcher is used for Operator to launch demo games. Operator can build a Demo Play Launch URL
for each game which supports demo play, and use it to launch a specific game.

URL: https://<KMLobbyServerURL>/demolauncher
HTTP method: GET

Method Parameters:
Parameter Definition Required (Y/N) Type
String
gpcode Game provider code, e.g., "KMQM". See Appendix K Y
Max length: 50
String
gcode Game code. Y
Max length: 50
lang Language code used by the player. String
Y
See Appendix D for the list of language codes. Length: 5

Example URLs:
https://staging-lobby.queenmakergames.co/demolauncher?gpcode=KMQM&gcode=thai_hi_lo_2&lang=en-US

9.6 Launch Demo Games

Here is a complete example that shows each step to launch demo play for a table game, including

1. Generate a brand access token. (please ignore this step if you are new integration)
2. Get a game list from Game List API.
3. Launch the game using Demo Play Launcher.

1) Generate a brand access token (please ignore this step if you are new integration)

REQUEST:
POST /api/oauth/token HTTP/1.1
Host: staging-api.queenmakergames.co
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=playerapi&client_id=Operator-Integration&client_secret=1uuvtpXapvS6RwslyA2FgrZQA
7V5EoPNT8djr0o8wqf1

RESPONSE:
{
"access_token": "wgwPwspacMCOs8ODUAUx8thZYvV0krkgKZCYeWZGdmi7pPEgxbbMLzrWFzHuQPqy2",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "playerapi"
}

KINGMAKER - Operator API Integration Guide v1.25

 77

2) Get a game list from Game List API

Note: “supportdemourl”: true will be returned if games support demo play

REQUEST:
GET /api/games?lang=en-US&platformtype=0 HTTP/1.1

Host: staging-api.queenmakergames.co
X-QM-ClientId: 0e1d1034f981499e
X-QM-ClientSecret: lPbZ6yGPScSKpuJUj7pRqKmANVKh
Authorization: Bearer wgwPwspacMCOs8ODUAUx8thZYvV0krkgKZCYeWZGdmi7pPEgxbbMLzrWFzHuQPqy2
Accept: application/json

RESPONSE:
{
"iconres": [
"343x200",
"520x520"
],
"games": [
{
"externalid": "thai-hi-lo-2",
"code": "thai_hi_lo_2",
"name": "Thai Hi Lo 2",
"description": "Thai Hi-Lo is a Thailand version of high or low (Hi-Lo), that is played with three dice in a shaker.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,
"supportdemourl": true
},

{
"externalid": "dragon-tiger-2",
"code": "dragon_tiger2",
"name": "Dragon Tiger 2",
"description": "Dragon Tiger is a very simple card game. The dealer will draw two cards, one for the dragon and one for the
tiger.",
"providercode": "KMQM",
"isactive": true,
"type": 1,
"iconurl": null,
"betlimits": null,
"supportdemourl": true
}
]
}

3) Launch the game using Demo Game Launcher

Based on the information from previous steps, to launch KingMaker game "Thai Hi Lo 2", the Game Launcher URL is

https://staging-lobby.queenmakergames.co/demolauncher?gpcode=KMQM&gcode=thai_hi_lo_2&lang=en-US

KINGMAKER - Operator API Integration Guide v1.25

 78

Appendix
Appendix A - Table of OAuth Errors

Error Code Description Note

For example, missing required property in the

invalid_request Invalid request
request

unauthorized_client Unauthorized client Incorrect client_id or client_secret

invalid_scope Invalid scrope

server_error Server error

under_maintenance Brand under maintenance

Appendix B - Supported HTTP Status Codes

Status Code Definition Note

200 OK Request is being executed successfully with expected operation result

400 Bad Request For example, missing Authorization Bearer header

401 Unauthorized For example, failed to get access token or authorize a player

404 Not Found Resource could not be found. For example, incorrect API endpoint or path

405 Method Not Allowed Incorrect HTTP verb used (GET, POST) or unsupported HTTP method

500 Internal Server Error

503 Service Unavailable

Appendix C - VIP Levels

VIP Level ID Description

1 Bronze - basic limits

2 Silver - upgraded limits

3 Gold - high limits

4 Platinum - VIP limits

KINGMAKER - Operator API Integration Guide v1.25

 79

Appendix D - Languages
The following table shows language codes defined in the KM platform.
Language Code Description

en-US English (English) : default

zh-CN Simplified Chinese (简体中文)

zh-TW Traditional Chinese (繁體中文)

ja-JP Japanese (日本語)

ko-KR Korean (한국어/조선말)

th-TH Thai (ภาษาไทย)

vi-VN Vietnamese (ngôn ngữ tiếng Việt)

id-ID Indonesian (bahasa Indonesia)

Appendix E - Currencies
The following table shows currency code defined in KM platform.
Currency Code Description

RMB Renminbi

EUR Euro

USD US Dollar

GBP Pound Sterling

JPY Japanese Yen

THB Thai Baht

VND Vietnamese Dong

VND_1000 Deflated Vietnamese Dong (VND/1000)

IDR Indonesian Rupiah

IDR_1000 Deflated Indonesian Rupiah (IDR/1000)

INR Indian Rupee

MMK Myanmar Kyat

MMK_1000 Deflated Myanmar Kyat (MMK/1000)

MYR Malaysian Ringgit

PHP Philippine Peso

KINGMAKER - Operator API Integration Guide v1.25

 80

Appendix F - Transaction Types (txtype)

ID Description Notes

500 Place bet

510 Win bet

511 Win Jackpot

520 Lose bet

530 Free bet

540 Tie bet

560 Cancel transaction

590 End round

600 Fund in the player's wallet

610 Fund out the player's wallet

611 Cancel fund-out

Appendix G - Bonus Types (bonustype)

ID Description Notes

0 No bonus

Appendix H - Game Types

ID Description Notes
0 Slot
1 Table Game

KINGMAKER - Operator API Integration Guide v1.25

 81

Appendix I - Table of Errors for External Wallet Integration

Error ID Description Note

12 Invalid or expired access token Refresh access token when getting this error
20 Player disabled
60 Invalid amount Credit or debit a player with less than or equal to 0
100 Insufficient funds Player has insufficient funds to debit
200 Transaction not found
300 Invalid arguments For example, missing required property in the request
400 Missing Authorization Bearer header
500 Incorrect format Invalid tag format when authorizing a player
600 Player not found
700 Brand under maintenance
900 System error

Appendix J - Table of Errors for Single Wallet Integration

Error ID Description Note

10 Invalid or expired token

19 Invalid token scope
20 User blocked
30 Invalid Credential
50 Currency Mismatch
100 Insufficient funds to perform the operation
300 Invalid arguments: {argument name or reason} example:Invalid arguments: userid not exist.
400 Missing token
500 Incorrect format. {further detail if any} example:Incorrect format: '2016-03-20 23:01.9999'
600 Transaction does not exist
610 Transaction already cancelled
800 Operation Failed Deterministically
900 System Error. {further detail if any} This is for non-deterministic failure.
903 Configured Timeout Exceeded

Appendix K - Table of Game Providers

Code Name Game Type Support Test Player (Y/N)

KMQM KingMaker QM Table Game Y

RT Red Tiger Slot, Table Game Y
OG One Game Slot N

KINGMAKER - Operator API Integration Guide v1.25

 82

Appendix L - Platform Types

Code Platform

0 Desktop
1 Mobile

Appendix M - Table of Games Having In-Game Fund Transfer

Game Provider Code Game Provider Name Game Code Game Name

KMQM KingMaker QM Gao_Gae Gao Gae

KMQM KingMaker QM Kingmaker_Pok_Deng Kingmaker Pok Deng
KMQM KingMaker QM Pai_Kang Pai Kang
KMQM KingMaker QM Blackjack Blackjack
KMQM KingMaker QM Teen_Patti Teen Patti
KMQM KingMaker QM 5_Card_Poker 5 Card Poker
KMQM KingMaker QM Bola_Tangkas Bola Tangkas

KINGMAKER - Operator API Integration Guide v1.25

 83

Version History
Version Date Description of Changes Author
1.0 01-Jun-2020 Initial draft Pete Chen
Change parameter “timestamp” from Required to Optional for section 7.4 Wallet Credit and 7.5
1.1 23-Jun-2020 Jerry Yeh
Wallet Debit
1.2 21-Jul-2020 Revise KingMaker GP code Jerry Yeh
1.3 27-Jul-2020 Revise the Currencies list in Appendix Jerry Yeh
1.4 21-Aug-2020 Add OneGame GP code Jerry Yeh
1.5 26-Aug-2020 Add content-type and accept header format in the sections 6.3, 6.4, 7.4, 7.5, 9.1 and 10 Pete Chen
Add section 5.2 and update section 5.1
1.6 27-Aug-2020 Pete Chen
Update section 6, 7, 9 and 10 for new API authorization mechanism
1.7 09-Sep-2020 Update section 8.2, 8.3, 8.4, 8.5 and 8.6 for new API authorization mechanism Pete Chen
1.8 16-Oct-2020 Updated section 7.6.2 Pete Chen
Updated section 7.6.4 playtype sample json
Owen Chen
1.9 27-Oct-2020 Updated Appendix F - Transaction Type
Pete Chen
Removed unlockamt from section 8
1.10 04-Jan-2021 Updated section 8.5 Pete Chen
1.11 19-Jan-2021 Updated section 7.6.2, 7.6.3 and 7.6.4 for Accept-Encoding header Pete Chen
1.12 08-Jun-2021 Updated section 7.3.2 and 7.3.3 Pete Chen
1.13 16-Aug-2021 Updated section 9.4 Pete Chen
1.14 14-Oct-2021 Updated parameter notes for section 7.6.1, 7.6.3 and 7.6.4 Pete Chen
1.15 28-Oct-2021 Updated parameter notes for section 9.1 Pete Chen
1.16 09-Mar-2022 Updated parameter notes for section 7.6.10 Luke Hu
1.17 08-Jul-2022 Updated correct JSON response for section 7.6.5 Pete Chen
1.18 21-Nov-2022 Updated section 8.5 Pete Chen
1.19 25-Nov-2022 Added Appendix M Pete Chen
1.20 02-Dec-2022 Updated section 8.10 Pete Chen
1.21 31-Jan-2023 Updated section 7.6.10 Jerry Yeh
1.22 03-Mar-2023 Updated section 8.3 and 8.4 Jerry Yeh
1.23 20-Mar-2023 Added section 7.6.11 Pete Chen
Removed section 10
1.24 25-APR-2023 Pete Chen
Updated section 7.6.8 and 7.6.9
1.25 26-APR-2023 Updated some wordings Pete Chen

KINGMAKER - Operator API Integration Guide v1.25