API Reference

The KiX server provides some useful APIs, allowing the game to interact more deeply with the players.

Note: When developers create a game on the KiX platform, they will receive two pieces of information: appId and appKey. The appKey is a sensitive piece of information and should be kept secure.

Server API includes the server-side API interface for player purchases, rewards, message sending and other operations, which is provided to the game server to achieve a deep integration between the game and the players.

Note: For data security reasons, Server API in a production environment only allows game servers to access using specific IP addresses. Please configure the IP address of the game server in the platform.

Server API Address

The server API address of the KiX game is:

https://game-gateway.lobah.net

Authentication

The APIs provided by the KiX server use the HmacMD5 algorithm for authentication to ensure data security. Therefore, the developer's game server needs to calculate the authentication string using the following algorithm each time a request is made:

macMD5 ( URLEncode ( "POST" + Request path + Request parameters + Request body ), appKey )

The example data above will generate the content of the string to be encrypted as follows:

POST/1.0/open-gateway/game/send-messageaccess_token=4d0b364bcd2e9c6243b149e2e2a2c65a&app_id=92&nonce=89e8379b&ts=1730970702&uid=1005008&zone=SA{ "content": "hello world", "id_list": [ 1005008 ], "operator": "Test Game" }

The string to be encrypted, after URL encoding, will result in the following content:

POST%2F1.0%2Fopen-gateway%2Fgame%2Fsend-messageaccess_token%3D4d0b364bcd2e9c6243b149e2e2a2c65a%26app_id%3D92%26nonce%3D89e8379b%26ts%3D1730970702%26uid%3D1005008%26zone%3DSA%7B+%22content%22%3A+%22hello+world%22%2C+%22id_list%22%3A+%5B+1005008+%5D%2C+%22operator%22%3A+%22Test+Game%22+%7D

The authentication string calculated using HmacMD5 is:

114921f6dd2c59477f34c76647249e3d

When making the POST request using the authentication string calculated with the above algorithm, IT IS IMPORTANT to append &sig=authentication_string at the end of the request parameters. Therefore, the final request URL will be as follows:

https://api-test.lobah.net/1.0/open-gateway/game/send-message?access_token=4d0b364bcd2e9c6243b149e2e2a2c65a&app_id=92&nonce=89e8379b&ts=1730970702&uid=1005008&zone=SA&sig=114921f6dd2c59477f34c76647249e3d

API Description

Certification Test

The game server can verify the authentication information through the authentication test interface to check if it is correct.

Request path: /1.0/open-gateway/game/test

Request method: POST

Data format: JSON

Request body:

{}

Response body:

ok

A 200 response code can be considered as an indication that the authentication information is correct.

Get User Profile

This API allow the game to obtain player information, including profile details like avatar, username, age, and Coin balance. This information can be used to personalize the in-game experience, displaying relevant data within the game UI.

Request path: /1.0/open-gateway/game/get-profile

Request method: POST

Data format: JSON

Request body:

{
    "app_id": "appId", 
    "token": "The `access_token` field passed from the client to the game.", 
    "uid": "User ID" 
}

Response body:

{
    "verify_status":"Verification result.",
    "user_id": "User ID",
    "avatar":"Avatar URL",
    "user_name":"User name",
    "user_coins": "User's Coins balance.",
    "level":"User's level",
    "gender":"User's gender"
}

The verify_status has three possible values:

• EXPIRED: The user's access_token has expired.
• LEGAL: The user's access_token is valid.
• ILLEGAL: The user's access_token is invalid.

gender will be 1 or 2, 1 means the user is male, 2 means female

If the session_id is an empty string, it means the user is not in the live room.

Request example:

{
    "app_id": 92, 
    "token": "4d0b364bcd2e9c6243b149e2e2a2c65a", 
    "uid": 1005008 
}

Response example:

{
    "verify_status":"LEGAL",
    "user_id":1005008,
    "avatar":"https://d1d7fyvslid3cf.cloudfront.net/images/2021/3/12/12/e7c6634011b84f5e9e30607b653babaf",
    "user_name":"Grevfvv",
    "user_coins":22514, 
    "level":15,
    "gender": 1
}

Note that in previous versions of the document, get-profile will return the session_id field, which is deprecated. Please obtain the session id of the current live room from the game URL or Game SDK.

Send Coins to the user

The game can reward players with a certain amount of coins, and the reward amount is paid from the available coins in the game.

Please note that the coins that can be used for rewards in the game and the game income when players purchase are separated.

Request path: /1.0/open-gateway/game/reward

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "rewards": [ 
        { 
            "amount": "Reward amount", 
            "reference_id": "The ID generated by the game server, used to distinguish each reward record.", 
            "type": "coins", 
            "uid": "User ID"
        }
    ], 
    "session_id": "The live room ID"
}

The field rewards is an array, allowing multiple sets of rewards to be issued simultaneously.

The session id is optional. It can be in the form of a number or a string. It is ultimately stored in the form of a number.

Response body:

{
"result":[
    {
        "reward_id":"Reward ID",
        "reference_id":"The ID generated by the game server, used to distinguish each reward record.",
        "status": "Resule status",
        "availableCoinsCredit": "The total amount of coins that can be used for game rewards"
    }]
}

The result array corresponds to the results of the multiple rewards specified in the rewards field of the request. Developers can use the reference_id to filter the results for each reward.

The possible values for status are as follows:

• 0: Success
• 11: Rejected
• 12: Reward amount is 0, no action taken
• 13: Insufficient Coins in the game
• 14: Invalid reward type
• 20: Other error

Request example:

{ 
    "app_id": 92, "rewards": [ 
        { 
        "amount": 10, 
        "reference_id": "6a5aca7bfc66", 
        "type": "coins", 
        "uid": 1005008 }
     ], 
    "session_id": "1234567890"
 }

Response example:

{
    "result":[
        {
        "reward_id":"G92-1-R17309707032943514",
        "reference_id":"6a5aca7bfc66",
        "status":0, 
        "availableCoinsCredit": 10233
        }
    ]
}

Player payment

Games can offer players paid features, such as purchasing items or additional attempts.

Before using the purchase function, it is necessary to pre-arrange with the KiX gaming platform the products to be purchased and their prices. Players will use KiX Coins for the purchase settlement. The balance of Coins that a player owns can be checked through the Get User Prifile API.

Request path: /1.0/open-gateway/game/purchase

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "product_id": "specified product ID",
    "reference_id": "an ID generated by the game server to identify this transaction record, this ID must be unique across all transactions",
    "session_id": "The live room ID",
    "uid": "User ID"
}

Important note: Because the amount parameter is easily confused with other API, and considering the habit of using the purchase API, The amount parameter is DEPRECATED in the purchase API and it can be ignored. When the purchase API is used, the coins amount paid by the player is determined by the product ID.

The product_id is agreed upon by KiX and the developer.

The session id is optional. It can be in the form of a number or a string. It is ultimately stored in the form of a number.

Response body:

{
    "purchase_result_code": "result code",
    "balance": "the balance held by the game",
    "user_coins": "the user's Coins balance",
    "order_id": "transaction ID, used for refunds"
}

The results for purchase_result_code are as follows:

• 0: Purchase successful
• 10: Incorrect appId
• 11: Incorrect product_id
• 12: Insufficient user Coins
• 13: Duplicate or invalid reference_id
• 20: Other errors

Request example:

{ 
    "app_id": 92, 
    "product_id": "GAME.SHOP.TEST.10COIN",   
    "reference_id": "29135edafa9d", 
    "session_id": "1234567890", 
    "uid": 1005008 
}

Response example:

{
    "purchase_result_code":0,
    "balance":290,
    "user_coins":22514,
    "order_id":"G92-P17309707027364314"
}

Refunds

After a purchase operation, a refund operation can be performed on the transaction. After the refund, the Coins spent on the purchase will be returned to the player's account.

Request path: /1.0/open-gateway/game/refund

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "order_id": "the transaction ID returned at the time of purchase"
}

Response body:

{
    "result": "result code"
}

The results for result are as follows:

• 0: Refund successful
• 10: Incorrect order_id
• 11: Rejected
• 20: Other errors

Request example:

{ 
    "app_id": 92, 
    "order_id": "G92-P17309707027364314" 
}

Response example:

{
    "result":0
}

Top Players

The game server can provide the Top Players data, displaying players from the KiX platform on the game's leaderboard.

Request path: /1.0/open-gateway/game/top-players

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId", 
    "rankings": [
       { "uid": "user ID", "score": "user score" }
    ] 
}

User scores are ranked in descending order.

Response body:

{
    "ok": "boolean"
}

When ok is true, the data has been successfully written; when false, it indicates an error occurred.

Request example:

{
    "app_id": 92, 
    "rankings": [ 
        { "uid": 1000064, "score": 98 }, 
        { "uid": 1000063, "score": 101 } 
    ] 
}

Response example:

{
    "ok":true
}

Mark Playing Status

This API can display the game player information on the currently playing tab in the room.

Request path: /1.0/open-gateway/game/mark-players

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId", 
    "rankings": [
       { 
         "uid": "user ID",
         "score": "user score",
         "session_id": "room id"
       }
    ] 
}

Each call to this interface will overwrite the previous data for easy updating.

The session id is the player's current room ID. If the room ID is set, players with the same room ID will be displayed in the same room. If it is not set, all players will be displayed.

Response body:

{
    "ok": "boolean"
}

When ok is true, the data has been successfully written; when false, it indicates an error occurred.

Request example:

{
    "app_id": 92, 
    "rankings": [ 
        { "uid": 1000064, "score": 98, "session_id": 1234456661 }, 
        { "uid": 1000063, "score": 101, "session_id": 1234456661 } 
    ] 
}

Response example:

{
    "ok":true
}

Get Product List

This API can obtain available Product information.

Request path: /1.0/open-gateway/game/product-list

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId"
}

Response body:

{
    "products":
        [
            {
                "product_id": "Product ID",
                "coins": "Product price",
                "description": "Product description"
            }
        ]
}

All available product information will be listed here, and the product_id is used for the purchase API.

Request example:

{
    "app_id": 92
}

Response example:

{
    "products":
    [
        {"product_id":"GAME.SHOP.TEST.COIN12","coins":12,"description": ""},
        {"product_id":"GAME.SHOP.TEST.COIN34","coins":34,"description": ""}
    ]
}

Transactions

The Transaction API is a set of APIs used to perform multiple payment and reward operations for different users during a game session or phase, followed by a one-time settlement.

1. Start a Transaction

Request path: /1.0/open-gateway/game/transaction/start

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "reference_id": "A unique ID generated by the game server to distinguish this request."
}

Note: The reference_id must be unique; duplicate reference_id values will cause the call to fail.

Response body:

{ 
    "app_id": "appId",
    "reference_id": "Passed reference_id",
    "transaction_id": "This transaction's ID",
    "result_code": "Result Code"
}

Values for result_code:

• 0: Transaction started successfully.
• 10: Invalid app_id.
• 13: Invalid or duplicated reference_id.
• 20: Other errors.

Request example:

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b"
}

Response example:

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b",
    "transaction_id": "TRX7-17434811375622102",
    "result_code": 0
}

2. Check the Transaction Status

Request path: /1.0/open-gateway/game/transaction/status

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID"
}

Response body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "result_code": "Result Code"
}

Values for result_code:

• 0: Transaction in progress.
• 2: Transaction already closed.
• 10: Invalid app_id.
• 15: Non-existent transaction_id.
• 20: Other errors.

Request example:

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b"
}

Response example:

{
    "app_id": 7,
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 0,
    "total_deducted_amount": 0,
    "result_code": 0
}

3. Send Coins to User in a Transaction

Request path: /1.0/open-gateway/game/transaction/add

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "A unique ID generated by the game server to distinguish this request.",
    "amount": "Number of coins to send",
    "uid": "User ID",
    "session_id": "Current room ID where the user is located"
}

Response body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "Passed reference_id",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "user_coins": "User's current coin balance",
    "uid": "User ID",
    "result_code": "Result Code"
}

Values for result_code:

• 0: Operation successful.
• 2: Transaction already closed; this call is invalid.
• 10: Invalid app_id.
• 13: Invalid or duplicated reference_id.
• 15: Non-existent transaction_id.
• 16: Total sent amount exceeds total debited amount; this call is invalid.
• 20: Other errors.

Request example:

{
    "amount": 5, 
    "app_id": 7,  
    "transaction_id": "TRX7-17434811375622102",   
    "reference_id": "66e0702321da", 
    "session_id": 1733800215637628, 
    "uid": 1000064
}

Response example:

{
    "app_id": 7,
    "reference_id": "66e0702321da",
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 5,
    "total_deducted_amount": 15,
    "user_coins":6060,
    "uid": 1000064,
    "result_code": 0
}

4. Deduct Coins from User in a Transaction

Request path: /1.0/open-gateway/game/transaction/deduct

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "A unique ID generated by the game server to distinguish this request.",
    "amount": "Number of coins to deduct",
    "uid": "User ID",
    "session_id": "Current room ID where the user is located"
}

Response body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "Passed reference_id",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "user_coins": "User's current coin balance",
    "uid": "User ID",
    "result_code": "Result Code"
}

Values for result_code:

• 0: Operation successful.
• 2: Transaction already closed; this call is invalid.
• 10: Invalid app_id.
• 12: Insufficient user balance; this call is invalid.
• 13: Invalid or duplicated reference_id.
• 15: Non-existent transaction_id.
• 20: Other errors.

Request example:

{
    "amount": 15,
    "app_id": 7,  
    "transaction_id": "TRX7-17434811375622102",   
    "reference_id": "08ec79b4c0dc", 
    "session_id": 1733800215637628, 
    "uid": 1000064
}

Response example:

{
    "app_id": 7,
    "reference_id": "08ec79b4c0dc",
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 0,
    "total_deducted_amount": 15,
    "user_coins":6060,
    "uid": 1000064,
    "result_code": 0
}

5. Close a Transaction

Request path: /1.0/open-gateway/game/transaction/close

Request method: POST

Data format: JSON

Request body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID"
}

Response body:

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "result_code": "Result Code"
}

Values for result_code:

• 0: Operation successful.
• 2: Transaction already closed.
• 10: Invalid app_id.
• 20: Other errors.

Request example:

{ 
    "app_id": 7,   
    "transaction_id": "TRX7-17434811375622102" 
}

Response example:

{
    "app_id": 7,
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 5,
    "total_deducted_amount": 15,
    "result_code": 0
}