3️⃣

3. item purchase request

This includes shop item purchase verification, purchase information storage, temporary purchase number, and delivery of a one-time payment URL.

Basic Info

POST /bill-store/v2.0/{{service_id}}/purchase
Host:
   https://api.onstove.com (LIVE)    
   https://api.gate8.com (SB)   
Content-Type: application/json
JavaScript
복사

Request

Header

Name	Type	Required	Default Value	Example	Description
authorization	String	Y	-	{access_token}	Access token issued through user authentication ※ On the web, the "SUAT cookie value" is used
X-Lang	String	Y	-	ko	Language code
X-Nation	String	Y	-	KR	Country code
X-Timezone	String	Y	-	Asia/Seoul	Timezone
X-Utc-Offset	Int32	Y	-	540	UTC Offset
caller-id	String	Y	-	clientapp	API Caller Information Example: ServiceName_GAME_SERVER

Path Variable

Name	Type	Required	Default Value	Example	Description
service_id	String	Y	-	GAME_ID	Game ID issued by the studio

Body

Name	Type	Required	Default Value	Example	Description
shop_key	String	Y	-	indie	In-game shop key
pguid	String	N	-	-	Platform Member Guid
character_no	String	N	-	-	Character Number
world_id	String	N	-	AAA	World ID
guid	Int64	Y	-	123456	Character number or in-game unique key - character_no > pguid > member_no (transmitted in this order)
shop_purchase_tran_id	String	N	-	38dc674b-1c06-407e-bfb3-ea12641d2b36	Unique Purchase Key - Used for verification via the noti API when the received Key is NULL. - If NULL, the store must issue a unique value each time - A unique value must be passed each time it is called.
access_token	String	Y	-	-	Access token issued through user authentication • Token value for generating billing web cookie values
product_infos	List<json object>	Y	-	-	Purchased Item Information
price	Double	Y	-	1000	Total Purchase Price • Sum of sale_price from product list
ingame_flag	bool	Y	true	true	In-game call - When calling from the web, false must be passed.
test_mode	bool	N	false	false	Test Mode • Only games listed in the Store (Studio) are permitted
billing_token	String	N	-	e994539c1f96494da83c49cf7ecd90cc	Billing Token (Internal Use) • Excluded from the Developer Center
service_txn_no	String(50)	N	-	"123456789"	Service Order Number • Order number issued by the game • Transmitted via the NOTI server
extra_data	String(500)	N	-	"{\"birth_dt\": 593871400000, \"rating\": \"18\"}"	Additional Request Data (JSON string) • Additional information to be received from the game • Transmitted via the NOTI server
steam_id	Int64	N	-	123456	Steam ID

product_infos

Name	Type	Required	Default Value	Example	Description
product_id	Int64	Y	-	1001	Platform-specific item ID
quantity	Int32	N	1	1	Quantity • Quantity you wish to purchase

Response

Body

Name	Type	Required	Default Value	Example	Description
code	Integer	Y	-	0	Response code
message	String	Y	-	OK	Response message
value	Object	N	-		Response value

Value

Name	Type	Required	Default Value	Example	Description
txn_mst_no	Int64	Y	-	4613050609508317204	Unique Transaction Master Number (Payment TID)
shop_purchase_tran_id	String	Y	-	81f71693-5239-49e3-beff-8e70fea4b15d	Shop Purchase Transaction ID
temp_payment_url	String	N	-	http://pay-dev.onstove.com/payment/BP/649edc28a5e04176b4be754321558b92	Single-use payment URL - If a steam_id exists, return NULL.
purchase_progress	Int	Y	-	0	Purchase Progress Status • 1: Payment in Progress: Requires calling the payment window • 2: Purchase Complete: Item delivery completed with a 0 won purchase
extra_data	String	N	-	{\"birth_dt\": 593871400000, \"rating\": \"18\"}	Get the data from buy_end_noti_api
txn_dtl_nos	Array<Int64>	Y	-	[46130506095083171234, 4613050609508312341]	Purchase Detail Number (Purchased Item TID)

Sample

Request

curl --location --request POST'https://api.onstove.com/bill-store/v2.0/{{service_id}}/purchase' \
--header 'Authorization: Bearer {{access_token}}'
--header 'X-Lang: ko'
--header 'X-Nation: KR'
--header 'X-Timezone: Asia/Seoul'
--header 'X-Utc-Offset: 540'
--header 'caller-id: {{caller-id}}'
{
    "shop_key": "TESTKEY",
    "pguid": "123456789",
    "character_no": "123456789",
    "world_id": "AAA",
    "guid": null,
    "shop_purchase_tran_id": null,
    "access_token": "{access_token}"
    "product_infos": [    
        {
            "product_id": 1835,
            "quantity": 1
        }
    ],
    "price": 1000,
    "ingame_flag": true,
    "steam_id": 123456
}
JavaScript
복사

Response

Content-Type : application/json

{
    "value": {
        "txn_mst_no": 4613050609508317204,
        "shop_purchase_tran_id": "de43fed6-ab97-46b9-9ae4-76ad7e824a4f",
        "temp_payment_url": "http://pay-dev.onstove.com/payment/BP/649edc28a5e04176b4be754321558b92",      
        "extra_data": null,
        "purchase_progress": 1,
        "txn_dtl_nos": [46130506095083171234, 4613050609508312341]
    },
    "code": 0,
    "message": "OK"
}
JavaScript
복사

Response Failure Example

{
  "code": "999999",
  "message": "An undefined error."
}
JavaScript
복사

Return Code

HTTP Status code	response_code	response_message	Description
200	0	OK	Success
200	999999	An undefined error has occurred.	Item Shop API Error
	50001	The store does not exist or is currently undergoing maintenance.	Item Shop API Error
	50002	The product does not exist or is unavailable for sale.	Item Shop API Error
	50003	This is a non-exhibition item.	Item Shop API Error
	50004	This item is not currently on sale.	Item Shop API Error
	50005	The product price does not match. (If the product price has changed) • This includes cases where the product price is negative.	Item Shop API Error
	50009	Exceeded the maximum number of items available for purchase (per member)	Item Shop API Error
	50010	Exceeded available sales quantity (total sales quantity)	Item Shop API Error
	50011	Exceeded maximum purchase quantity (Character (GUID))	Item Shop API Error
	50015	Exceeded the maximum number of items available for purchase (World)	Item Shop API Error
	50031	The purchase quantity cannot be less than 1.	Item Shop API Error
	50032	Payment services are not available in your country.	Item Shop API Error
	50033	Incorrect login information.	Item Shop API Error
500	500	Internal Server Error	Internal server error