TOP/APIドキュメント | API Documentation/REST API Specification 0.0.3

REST API Specification 0.0.3

2025/3/4 17:552025/6/19 13:51

This document provides specifications for integrating with the Game8 Store API.

Index

API List Publisher APIs 1. Common Specifications 1.1. Request Specifications 1.1. Request Headers 1.2. Response Specifications 1.3. X-Signature Configuration 2. Publisher APIs 2.1. Purchase Eligibility Check (GET /check) Required 2.2. Register Purchase (POST /register) Required 2.5. Retrieve Player Information (GET /user_info)Recommended 3. Error Handling 3.1. Error Code List 3.2. Recommended Error Handling Flow 3.3. Retry Policy

API List

Publisher APIs

Game8 Store calls these APIs.

API Name	Required	Description
Purchase Eligibility Check	Required	Checks if a user is eligible to purchase a specified item
Register Purchase	Required	Grants in-game items after purchase completion
Retrieve Player Information	Recommended	Retrieves the player's name and level based on their in-game ID.

1. Common Specifications

Item	Details
Host	Game8-provided APIs: Publisher-provided APIs:
Protocol	HTTPS
Character Encoding	UTF-8

1.1. Request Specifications

1.1. Request Headers

Key	Value	Description
Authorization	Bearer	Authentication information
Content-Type	application/json	Content type
X-Signature		Signature for verification

The access token must be a randomly generated string of 16 to 36 alphanumeric characters, including both uppercase and lowercase letters, issued for each game.

Game8, Inc. will generate and provide the access token. However, if you prefer to generate it yourself, please contact us.

1.2. Response Specifications

Common Response Headers

Key	Value
Content-Type	application/json

Common Response Body

Key	Value	Description
request_id		A unique request ID. Used for tracking requests during troubleshooting.
timestamp		Response timestamp
result_code		Result code
message		Message

If an error from the error code list occurs, only the common response body fields will be returned.

1.3. X-Signature Configuration

To verify whether a request is legitimate, a game-specific shared secret key is used to sign the request, which is then included in the request header for validation.

Signature Generation Process

Calculate the digest based on the query string for GET requests and the request body for POST requests. The digest is calculated using HMAC-SHA256 with the shared secret key.

Examples of messages used for digest calculation

For GET: game=game123&user=user456&...

For POST: {"game":"game123","user":"user456",...}

Encode the computed digest in Base64 and set it in the request header as .

Signature Verification Process

Calculate the digest based on the query string for GET requests and the request body for POST requests.The digest is calculated using HMAC-SHA256 with the shared secret key.

Examples of messages used for digest calculation

For GET: game=game123&user=user456&...

For POST: {"game":"game123","user":"user456",...}

Encode the computed digest in Base64 and compare it with the in the request header.

If they match, process the request as legitimate.
If they do not match, return an error as an invalid request.

How to Obtain the Secret Key

Game8, Inc. will generate and share the private key with you.

2. Publisher APIs

2.1. Purchase Eligibility Check (GET /check)

Overview

Checks whether an in-game item can be purchased, considering factors such as age restrictions and purchase limits.

To prevent purchase failures due to time lag in payment processing for limited-quantity items, a is used to secure the target item.

Request Specifications

Item	Details
Method	GET
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication information
Content-Type	application/json	Content type
X-Signature		Signature for verification

Query Parameter

Key	Type	Required	Description
game	string	✅	Unique game ID issued within Game8Store
user	string	✅	Unique in-game user ID issued within the game
transaction_id	string	✅	Identifier that uniquely identifies a transaction
item	string	✅	Unique ID of the item to be purchased within the game　（？）
price	integer	✅	Selling price of the item in Game8Store (tax included, JPY)

Request Example

Response Specifications

Response Body

Key	Type	Description
request_id	string	Unique request ID
timestamp	string (ISO8601)	Response timestamp
result_code	string	Result code
message	string	Message
purchasable	string	Purchase status: : Can be purchased : Cannot be purchased : Under maintenance
age_category	string	User's age category. Examples include , , , , and , but other values can be set as needed.
monthly_limit	integer	Monthly purchase limit (yen). means no limit.
remaining_limit	integer	Remaining purchase limit (yen). means no limit.
requested_price	integer	Requested item price (tax included, JPY)

Response Example (Purchasable)

Response Example (Not Purchasable - Age Verification Not Submitted)

Response Example (Not Purchasable - Purchase Limit Exceeded)

Response Example (Not Purchasable - Item Not Available for Sale)

Response Example (Not Purchasable - Under Maintenance)

2.2. Register Purchase (POST /register)

Overview

Processes the addition of in-game items after purchase completion.

We recommend implementing the following processes before registering purchase records:

Only accept requests that include a transaction_id that has passed through the item purchase eligibility check API

Verify that the purchase does not violate any purchase limitations

Request Specifications

Item	Details
Method	POST
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication information
Content-Type	application/json	Content type
X-Signature		Signature for verification

Request Body

Key	Type	Required	Description
game	string	✅	Unique game ID issued within Game8Store
user	string	✅	Unique in-game user ID issued within the game
item	string	✅	Unique ID of the item to be purchased within the game　（？）
transaction_id	string	✅	Identifier that uniquely identifies a transaction
item_name	string	✅	Name of the purchased item (e.g., "100 Gem Pack")
price	integer	✅	Selling price of the item in Game8Store (tax included, JPY)
contents	array	✅	List of contents included in the item

Data structure of the Array

Key	Type	Required	Description
content_id	string	✅	Automatically assigned content ID within the item, using as a prefix with a suffix (e.g., )
content_name	string	✅	Name of the content within the item (e.g., "Gem")
quantity	integer	✅	Quantity of the content within the item (e.g., 1000)

Request Example

Response Specifications

Response Body

Key	Type	Description
request_id	string	Unique request ID
timestamp	string (ISO8601)	Response timestamp
result_code	string	Result code
message	string	Message
item_granted	boolean	Whether the in-game item was granted ( / )

Response Example (Success)

Response Example (Failure - Unknown User)

Response Example (Failure - Already Registered Transaction ID)

2.5. Retrieve Player Information (GET /user_info)

Overview

Retrieves player name and level based on the game ID entered by the user. Displaying this information on the purchase confirmation screen allows users to verify the accuracy of their entered ID and confirm proper connectivity with the game.

Request Specifications

Item	Details
Method	GET
Endpoint
Protocol	HTTPS
Content Type

Request Headers

Key	Value	Description
Authorization		Authentication information
Content-Type		Content type
X-Signature		Signature for verification

Query Parameter

Key	Type	Required	Description
game	string	✅	Unique game ID issued within Game8Store
user	string	✅	Unique in-game user ID issued within the game

Request Example

Response Specifications

Response Body

Key	Type	Required	Description
request_id	string	✅	Unique request ID
timestamp	string (ISO8601)	✅	Response timestamp
result_code	string	✅	Result code
message	string	✅	Message
user_name	string	✅	Player name (can be masked)
user_level	integer	✅	Player level or rank. Returns if no such information exists in the game.

Since this API can retrieve other players' names using the entered in-game ID, consider masking player names as needed.

Masking Examples for

Player Name	Masked
aa	*a
aaa	*aa
aaaa	**aa
aaaaa	***aa

Response Example (Success)

Response Example (Failure - Player ID Not Found)

Response Example (Failure - Account Banned or Inactive)

Response Example (Failure - Server Maintenance)

3. Error Handling

3.1. Error Code List

Error Code	Description	Solution
	Success	-
	Invalid request format	Check the request structure and required parameters, and send in the correct format.
	Missing authentication credentials	Ensure the header contains the correct .
	Invalid access token	Check the token's validity and reissue it if necessary.
	Insufficient access permissions	Verify that the API endpoint has the necessary permissions.
	Signature mismatch	Ensure that the secret key used for the signature is correct.
	Processed requests	Ensure that duplicate are not sent.
	Missing required parameters	Check the required parameters and correct the request.
	Invalid parameter type	Example: If is sent as a , convert it to an integer.
	Invalid parameter value	Ensure no unauthorized or out-of-range values are sent.
	Data not found	Verify that the specified or exists.
	Purchase limit exceeded	Check the value and ensure it is within the allowed range.
	Age verification not completed	Prompt the user to complete age verification within the game.
	Item no longer available for sale	Contact the sales or development team for store adjustments.
	Account suspended, purchase unavailable	-
	Invalid transaction ID	Ensure that is correct.
	Specified user not found	Verify that the is correct.
	Specified item not found	Ensure that the is valid.
	Transaction ID already registered	Verify that is correct.
	Internal server error	A server-side issue may have occurred; retry after some time.
	Temporary system failure	Retry (recommended: retry after 5 seconds).
	Unknown error	Check the detailed error message and contact the development team.
	Under maintenance	The service is temporarily unavailable; retry after some time.

3.2. Recommended Error Handling Flow

Check the

If (Success), proceed as normal.

Otherwise, determine the type of error.

Determine if the error can be fixed on the client side

series and series errors can typically be resolved by correcting the request.

series errors require data consistency verification.

Check if the error is retryable

and are likely temporary errors, so retrying after a few seconds is recommended.

Log and report errors

For unknown errors (), record logs and notify the development team.

3.3. Retry Policy

Retry Interval	Max Retries	Notes
After 5 seconds	3 times	Internal server errors may be resolved quickly.
After 10 seconds	5 times	Longer interval recommended due to temporary system failures.
None	0 times	Unknown errors should be reported immediately.

Use this error handling list as a reference to implement proper error management in your system.