API Specification

Game8 Store API

API List

Publisher APIs

Game8 Store calls these APIs.

APIs Provided by Game8 Store

Publishers send requests to these APIs.

1. Common Specifications

1.1. Request Specifications

Request Headers

1.2. Response Specifications

Common Response Headers

Common Response Body

1.3. Configuring the X-Signature

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

1. 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.

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 query string for GET requests and the request body for POST requests. The digest is calculated using HMAC-SHA256 with the shared secret key.

1. Encode the computed digest in Base64 and compare it with the
   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)1 image

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

Request Specifications

Request Headers

Query Parameter

Request Example

GET /check HTTP/1.1
Host: <Optional (set by the publisher)>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=user456&transaction_id=txn_123456&item=item789&item_category=paid&price=500

Response Specifications

Response Body

Structure of account_limit

stock Structure

Response Example (Purchasable)

{
  "request_id": "abc123",
  "timestamp": "2025-02-04T12:34:56Z",
  "result_code": "PUB0000",
  "message": "Purchase allowed",
  "purchasable": "available",
  "age_category": "under_15",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

Response Example (Not Purchasable - Age Verification Not Submitted)

{
  "request_id": "abc124",
  "timestamp": "2025-02-04T12:35:00Z",
  "result_code": "PUB2006",
  "message": "Purchase is not allowed because age verification has not been completed.",
  "purchasable": "unavailable",
  "age_category": "unset",
  "account_limit": null,
  "stock": null,
  "requested_price": 500
}

Response Example (Not Purchasable - Purchase Limit Exceeded)

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2005",
  "message": "The purchase limit has been reached.",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 0,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

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

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2007",
  "message": "The target item is not available for sale.",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

Response Example (Not Purchasable - Under Maintenance)

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB6000",
  "message": "The service is currently under maintenance.",
  "purchasable": "maintenance",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

2.2. Register Purchase (POST /register)1 image

Overview

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

Request Specifications

Request Headers

Request Body

Data structure of the

Request Example

POST /register HTTP/1.1
Host: <Optional (set by the publisher)>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>

{
  "game": "game123",
  "user": "user456",
  "transaction_id": "txn789",
  "item": "pack001",
  "item_category": "paid",
  "item_name": "1,000 Gems",
  "price": 5000,
  "selling_price": 5000,
  "billing_amount": 5000,
  "purchased_at": "2025-02-04T12:36:00Z",
  "ref": "game8.jp",
  "payment_method": "Card",
  "contents": [
    {
      "content_id": "pack001-1",
      "content_name": "Gems",
      "quantity": 1000
    },
    {
      "content_id": "pack001-2",
      "content_name": "Bonus gold coins",
      "quantity": 100
    }
  ]
}

Response Specifications

Response Body

Response Example (Success)

{
  "request_id": "def456",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB0000",
  "message": "The purchase record has been registered.",
  "item_granted": true
}

Response Example (Failure - Unknown User)

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3002",
  "message": "The specified user does not exist.",
  "item_granted": false
}

Response Example (Failure - Already Registered Transaction ID)

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3004",
  "message": "The specified TransactionID has already been registered.",
  "item_granted": false
}

2.3. Retrieve Player Information (GET /user_info)1 image

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

Request Headers

Query Parameter

Request Example

GET /user_info HTTP/1.1
Host: <Optional (set by the publisher)>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=Player5678

Response Specifications

Response Body

user_name masking example

Response Example (Success)

{
  "request_id": "abc123",
  "timestamp": "2025-03-12T14:30:00Z",
  "result_code": "PUB0000",
  "message": "Retrieved successfully",
  "user_name": "****rX",
  "user_level": 45
}

Response Example (Failure - Player ID Not Found)

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2004",
  "message": "Player ID not found."
}

Response Example (Failure - Account Banned or Inactive)

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2008",
  "message": "Purchase not allowed due to account suspension."
}

Response Example (Failure - Server Maintenance)

{
  "request_id": "abc125",
  "timestamp": "2025-03-12T14:32:00Z",
  "result_code": "PUB6000",
  "message": "The service is currently under maintenance."
}

2.4. Inventory Check(GET /stock)Recommended

Overview

Checks the stock status of a specified item and returns the remaining purchasable quantity.
Used for displaying stock status to users for limited-quantity or campaign items, and for pre-purchase flow validation.

Request Specifications

Request Headers

Query Parameter

Request Example

GET /stock HTTP/1.1
Host: <Optional (set by the publisher)>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
	?game=game123&user=user456&transaction_id=txn_123456&items=item789,item012

Response Specifications

Response Body

stock Structure

Response Example (In Stock)

{
	"request_id": "abc123",
	"timestamp": "2025-02-04T12:34:56Z",
	"result_code": "PUB0000",
	"message": "Success",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 8,
		  "restock_at": null
	  }
	]
}

Response Example (Out of Stock)

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:35:00Z",
	"result_code": "PUB2009",
	"message": "Item purchase limit reached",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 0,
		  "restock_at": null
	  }
	]
}

Response Example (Unlimited Stock)

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:36:00Z",
	"result_code": "PUB0000",
	"message": "Success",
	"stock": [
	  {
	    "item": "item789",
		  "total": -1,
		  "remaining": -1,
		  "restock_at": null
	  }
	]
}

3. Game8 Store APIs

3.1. Order Verify (GET /orders/verify)Optional to Use

Overview

/register The status of orders notified via the API can be/register API.
/register transaction_id transaction_id /register /register paid_transaction_id
Intended use cases:

• /register notification
• Re-querying when a previous API call has failed

This enables anotification (/register) + verification (/orders/verify)double-confirmation pattern.

This API is always running on the Game8 Store side, and no prior application is required. You do not need to provide an endpoint on your side — to use this API, you only implement the call to it. Even if it is not integrated into your payment flow, you can check the payment status of an order by sending a request (use is optional).

Request Specifications

Request Headers

Query Parameter

Request Example

GET /api/public/marketplace/publishers/example-publisher/games/example-game/orders/verify HTTP/1.1
Host: <Game8specified by>
Authorization: Bearer <ACCESS_TOKEN>
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?paid_transaction_id=txn_123456

Response Specifications

Response Body (Success)

Status Values

Response Example (Success - Completed Order)

{
  "request_id": "abc123",
  "timestamp": "2025-04-01T12:00:00+09:00",
  "result_code": "PUB0000",
  "message": "Success",
  "paid_transaction_id": "txn_123456",
  "status": "completed",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 900,
  "billing_amount": 800,
  "purchased_at": "2025-04-01T12:00:00+09:00"
}

Response Example (Success - Pending Order)

{
  "request_id": "abc124",
  "timestamp": "2025-04-01T12:00:01+09:00",
  "result_code": "PUB0000",
  "message": "Success",
  "paid_transaction_id": "txn_123456",
  "status": "pending",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 1000,
  "billing_amount": 1000,
  "purchased_at": null
}

Error Response

When an error occurs, only the common response body fields are returned:

{
  "request_id": "<RequestID>",
  "timestamp": "<Timestamp>",
  "result_code": "<Error Code>",
  "message": "<Error message>"
}

Response Example (Error - Authentication Failed)

{
  "request_id": "abc125",
  "timestamp": "2025-04-01T12:00:02+09:00",
  "result_code": "PUB1002",
  "message": "Authentication or signature verification failed"
}

Response Example (Error - Order Not Found)

{
  "request_id": "abc126",
  "timestamp": "2025-04-01T12:00:03+09:00",
  "result_code": "PUB3001",
  "message": "The specified order was not found"
}

4. Error Handling

4.1. Error Code List

4.2. Recommended Error Handling Flow

1. result_code Check
   • PUB0000(Success), proceed as normal.
   • Otherwise, determine the type of error.
2. Determine if the error can be fixed on the client side
   • PUB1000 series and PUB2000 series errors can typically be resolved by correcting the request.
   • PUB3000 series errors require data consistency verification.
3. Check if the error is retryable
   • PUB4000, PUB4001 are likely temporary errors, so retrying after a few seconds is recommended.
4. Log and report errors
   • For unknown errors (PUB5000), keep a log and report it to the development team.

4.3. Retry Policy

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