page icon

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.
 

API List


Publisher APIs

Game8 Store calls these APIs.
API NameEndpointMethodRequiredDescription
Purchase Eligibility CheckRequiredChecks if a user is eligible to purchase a specified item
Register PurchaseRequiredGrants in-game items after purchase completion
Service Status CheckOptionalChecks whether the game service is running normally
Transaction ID ReleaseOptionalReleases reserved stock when a purchase is not finalized

Game8 APIs

Publishers will call these APIs.
API NameEndpointMethodRequiredDescription
Get Purchase HistoryOptionalRetrieves past purchase history for a specified user
Get Sales DataOptionalRetrieves sales data for a specified period

1. Common Specifications


ItemDetails
HostGame8-provided APIs: Publisher-provided APIs:
ProtocolHTTPS
Character EncodingUTF-8

1.1. Request Specifications

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature 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

KeyValue
Content-Typeapplication/json

Common Response Body

KeyValueDescription
request_idA unique request ID. Used for tracking requests during troubleshooting.
timestampResponse timestamp
result_codeResult code
messageMessage
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 shared secret key is used to sign the request, which is then included in the request header for validation.

Signature Generation Process

  1. Calculate a digest based on the request parameters for GET requests and the request body for POST requests.
    1. Compute HMAC-SHA256 using the shared secret key.
  1. Encode the computed digest in Base64 and set it in the request header as .

Signature Verification Process

  1. Calculate the digest based on the request parameters for GET requests and the request body for POST requests.
    1. Compute HMAC-SHA256 using the shared secret key.
  1. Encode the computed digest in Base64 and compare it with the in the request header.
    1. If they match, process the request as legitimate.
    2. 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

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store
userstringUnique in-game user ID issued within the game
transaction_idstringIdentifier that uniquely identifies a transaction
itemstringUnique ID of the item to be purchased within the game
priceintegerSelling price of the item in Game8Store (in yen)

Request Example

Response Specifications

Response Body
KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage
purchasablestringPurchase status: : Can be purchased : Cannot be purchased : Under maintenance
age_categorystringUser's age category. Examples include , , , , and , but other values can be set as needed.
monthly_limitintegerMonthly purchase limit (yen). means no limit.
remaining_limitintegerRemaining purchase limit (yen). means no limit.
requested_priceintegerRequested 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

ItemDetails
MethodPOST
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store
userstringUnique in-game user ID issued within the game
itemstringUnique ID of the item to be purchased within the game
transaction_idstringIdentifier that uniquely identifies a transaction
item_namestringName of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (in yen)
contentsarrayList of contents included in the item

Data structure of the Array

KeyTypeRequiredDescription
content_idstringAutomatically assigned content ID within the item, using as a prefix with a suffix (e.g., )
content_namestringName of the content within the item (e.g., "Gem")
quantityintegerQuantity of the content within the item (e.g., 1000)

Request Example

Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage
item_grantedbooleanWhether 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

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store

Request Example

Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage
service_statusstringStatus 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

ItemDetails
MethodPOST
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store
userstringUnique in-game user ID issued within the game
transaction_idstringIdentifier that uniquely identifies a transaction
itemstringUnique ID of the item to be purchased within the game
priceintegerSelling price of the item in Game8Store (in yen)

Request Example

Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage

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

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store
userstringUnique in-game user ID issued within the game
limitintegerMaximum number of history records to retrieve (default: 10)

Request Example

Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage
historyarrayList of purchase history records

Data Structure of the Array

KeyTypeDescription
transaction_idstringPayment transaction ID
itemstringItem ID
item_namestringName of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (in yen)
quantityintegerNumber of purchased items (e.g., 100)
timestampstring (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

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type
X-SignatureSignature for verification

Request Body

KeyTypeRequiredDescription
gamestringUnique game ID issued within Game8Store
start_datestring (YYYY-MM-DD)Start date of the retrieval period
end_datestring (YYYY-MM-DD)End date of the retrieval period

Request Example

Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Response timestamp
result_codestringResult code
messagestringMessage
total_salesintegerTotal sales amount within the period (yen)
total_feesintegerTotal fees within the period (yen)
net_salesintegerNet sales (total sales - fees) within the period (yen)
transactionsarrayList of sales transactions

Data Structure of the Array

KeyTypeDescription
transaction_idstringPayment transaction ID
itemstringItem ID
item_namestringName of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (yen)
quantityintegerNumber of purchased items (e.g., 100)
feeintegerFee amount (yen)
net_amountintegerNet sales amount (purchase amount - fee)
timestampstring (ISO8601)Purchase date and time

Response Example (Success)

4. Error Handling


4.1. Error Code List

Error CodeDescriptionSolution
Success-
Invalid request formatCheck the request structure and required parameters, and send in the correct format.
Missing authentication credentialsEnsure the header contains the correct .
Invalid access tokenCheck the token's validity and reissue it if necessary.
Insufficient access permissionsVerify that the API endpoint has the necessary permissions.
Signature mismatchEnsure that the secret key used for the signature is correct.
Processed requestsEnsure that duplicate are not sent.
Missing required parametersCheck the required parameters and correct the request.
Invalid parameter typeExample: If is sent as a , convert it to an integer.
Invalid parameter valueEnsure no unauthorized or out-of-range values are sent.
Data not foundVerify that the specified or exists.
Purchase limit exceededCheck the value and ensure it is within the allowed range.
Purchase restricted by ageVerify the and ensure compliance with restrictions.
Item no longer available for saleContact the sales or development team for store adjustments.
Invalid transaction IDEnsure that is correct.
Specified user not foundVerify that the is correct.
Specified item not foundEnsure that the is valid.
Transaction ID already registeredVerify that is correct.
Internal server errorA server-side issue may have occurred; retry after some time.
Temporary system failureRetry (recommended: retry after 5 seconds).
Unknown errorCheck the detailed error message and contact the development team.
Under maintenanceThe service is temporarily unavailable; retry after some time.

4.2. Recommended Error Handling Flow

  1. Check the
      • If (Success), proceed as normal.
      • Otherwise, determine the type of error.
  1. 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.
  1. Check if the error is retryable
      • and are likely temporary errors, so retrying after a few seconds is recommended.
  1. Log and report errors
      • For unknown errors (), record logs and notify the development team.

4.3. Retry Policy

Error CodeRetry IntervalMax RetriesNotes
After 5 seconds3 timesInternal server errors may be resolved quickly.
After 10 seconds5 timesLonger interval recommended due to temporary system failures.
None0 timesUnknown errors should be reported immediately.
Use this error handling list as a reference to implement proper error management in your system.