API Reference

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

Note: When developers create a game on the Lobah 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 Lobah game is:

https://game-gateway.lobah.net

Authentication

The APIs provided by the Lobah 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 elements involved in the algorithm calculation are as follows:

Name	Content	Explanation	Example
Request path	The API path to access.		/1.0/open-gateway/game/send-message
Request Parameters	Contains the following fields:
	uid	Passed from the client to the game, representing the user ID of the currently active player in the game.	1005008
	access_token	Passed from the client to the game for user authentication.	4d0b364bcd2e9c6243b149e2e2a2c65a
	app_id	appId	92
	nonce	A random string.	89e8379b
	ts	Current timestamp.	1730970702
	zone	Fixed to "SA"。	SA
Request body	The specific data to send to the API.		{ "content": "hello world", "id_list": [ 1005008 ], "operator": "Test Game" }

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://game-gateway.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

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"
}

verify_status There are 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 for male and 2 for female.

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

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.

Request example:

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" }

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
}

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 Lobah gaming platform the products to be purchased and their prices. Players will use Lobah 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 Lobah 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
• 14: User is a guest, guests cannot make purchases
• 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
}

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
}