REST API Specification 0.0.3
This document provides specifications for integrating with the Game8 Store API.
By using this API, publishers can perform actions such as:
- Checking purchase eligibility for in-game items
- Registering purchases and granting items
- Retrieving purchase history
- Obtaining sales data
We actively consider feedback and feature requests from publishers. If you have any suggestions or additional requirements, please feel free to contact us.
If you already have an existing publisher API, we will adjust our implementation to align with your specifications as much as possible.
Index
API ListPublisher APIsGame8 APIs 1. Common Specifications1.1. Request SpecificationsRequest Headers1.2. Response SpecificationsCommon Response HeadersCommon Response Body1.3. X-Signature ConfigurationSignature Generation ProcessSignature Verification ProcessHow to Obtain the Secret Key2. Publisher APIs2.1. Purchase Eligibility Check (GET /check) Required 2.2. Register Purchase (POST /register) Required2.3. Service Status Check (GET /service_status)2.4. Transaction ID Release (POST /release)3.Game8 APIs 3.1. Get Purchase History (GET /history)3.2. Get Sales Data (GET /sales)4. Error Handling4.1. Error Code List4.2. Recommended Error Handling Flow4.3. Retry Policy
API List
Publisher APIs
Game8 Store calls these APIs.
| API Name | Endpoint | Method | 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 | ||
| Service Status Check | Optional | Checks whether the game service is running normally | ||
| Transaction ID Release | Optional | Releases reserved stock when a purchase is not finalized |
Game8 APIs
Publishers will call these APIs.
| API Name | Endpoint | Method | Required | Description |
|---|---|---|---|---|
| Get Purchase History | Optional | Retrieves past purchase history for a specified user | ||
| Get Sales Data | Optional | Retrieves sales data for a specified period |
1. Common Specifications
| Item | Details |
|---|---|
| Host | Game8-provided APIs: Publisher-provided APIs: |
| Protocol | HTTPS |
| Character Encoding | UTF-8 |
1.1. Request Specifications
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 random string consisting of 16 to 36 alphanumeric characters, including both uppercase and lowercase letters.
You can generate it yourself, or we can create and provide one for you. If you would like us to generate it, 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 |
1.3. X-Signature Configuration
To verify whether a request is legitimate, a shared secret key is used to sign the request, which is then included in the request header for validation.
Signature Generation Process
- Calculate a digest based on the request parameters for GET requests and the request body for POST requests.
- Compute HMAC-SHA256 using the shared secret key.
- Encode the computed digest in Base64 and set it in the request header as .
Signature Verification Process
- Calculate the digest based on the request parameters for GET requests and the request body for POST requests.
- Compute HMAC-SHA256 using the shared secret key.
- 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 |
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 |
| 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 (in yen) |
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 (yen) |
Response Example (Purchasable)
Response Example (Not Purchasable - Age Restriction)
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 | ✅ | Purchase amount (in yen) |
| 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.3. Service Status Check (GET /service_status)
Overview
Checks whether the game service is operating normally and determines whether item purchases and other services are available.
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 |
Request Body
| Key | Type | Required | Description |
|---|---|---|---|
| game | string | ✅ | Unique game ID issued within Game8Store |
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 |
| service_status | string | Status of the service: |
| : Operational | ||
| : Not operational | ||
| : Under maintenance |
Response Example (Success)
2.4. Transaction ID Release (POST /release)
Overview
Releases the reserved stock for an item when the purchase was not finalized after the purchase eligibility check ().
However, if the item has already been granted in-game using the same transaction ID, the cancellation cannot be processed.
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 |
| 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 (in yen) |
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 |
Response Example (Success)
3.Game8 APIs
3.1. Get Purchase History (GET /history)
Overview
Publishers can use this endpoint to retrieve the purchase history of a specified user from the Game8 server.
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 |
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 |
| limit | integer | ❌ | Maximum number of history records to retrieve (default: 10) |
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 |
| history | array | List of purchase history records |
Data Structure of the Array
| Key | Type | Description |
|---|---|---|
| transaction_id | string | Payment transaction ID |
| item | string | Item ID |
| item_name | string | Name of the purchased item (e.g., "100 Gem Pack") |
| price | integer | Purchase amount (in yen) |
| quantity | integer | Number of purchased items (e.g., 100) |
| timestamp | string (ISO8601) | Purchase date and time |
Response Example (Success)
3.2. Get Sales Data (GET /sales)
Overview
Publishers can use this endpoint to retrieve sales data for a specified period from the Game8 server.
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 |
Request Body
| Key | Type | Required | Description |
|---|---|---|---|
| game | string | ✅ | Unique game ID issued within Game8Store |
| start_date | string (YYYY-MM-DD) | ✅ | Start date of the retrieval period |
| end_date | string (YYYY-MM-DD) | ✅ | End date of the retrieval period |
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 |
| total_sales | integer | Total sales amount within the period (yen) |
| total_fees | integer | Total fees within the period (yen) |
| net_sales | integer | Net sales (total sales - fees) within the period (yen) |
| transactions | array | List of sales transactions |
Data Structure of the Array
| Key | Type | Description |
|---|---|---|
| transaction_id | string | Payment transaction ID |
| item | string | Item ID |
| item_name | string | Name of the purchased item (e.g., "100 Gem Pack") |
| price | integer | Purchase amount (yen) |
| quantity | integer | Number of purchased items (e.g., 100) |
| fee | integer | Fee amount (yen) |
| net_amount | integer | Net sales amount (purchase amount - fee) |
| timestamp | string (ISO8601) | Purchase date and time |
Response Example (Success)
4. Error Handling
4.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. | |
| Purchase restricted by age | Verify the and ensure compliance with restrictions. | |
| Item no longer available for sale | Contact the sales or development team for store adjustments. | |
| 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. |
4.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.
4.3. Retry Policy
| Error Code | 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.