Check Possession Verification Code

This document explains how to use the API to verify whether the possession verification code sent via SMS or Email is valid.
Possession verification is provided through the following 2 APIs.

Request Possession Verification Code
Check Possession Verification Code (this document)

Please refer to the Identity Verification Service guide for integration methods and development flow.

Check Possession Verification Code API

Verifies whether the user has correctly entered the verification code sent by the Request Possession Verification Code API. Upon successful verification, it returns a possession_key that identifies the verification target.

Precautions

Prior consultation with the business manager is required before using this API.
The verification validity period is 3 minutes for SMS / 10 minutes for Email from the time the request API is called.
If multiple requests are made for the same target, all sent verification codes remain valid until their respective expiration times.
- If even one verification code is successfully verified, all verification codes for that target will expire.
Input error limit (Common for SMS & Email) : If the verification code is entered incorrectly 5 times for the same target (phone number / email) per game, the verification code for that target will be completely invalidated.
- If verification is successful even once, the failure count is reset.
- If the verification code is resent (request API called again), the failure count is reset. (New attempt count assigned to the new verification code)
- Since verification requests after complete invalidation will return 70104(no verification code issued), please guide the user to request a resend.
This API uses a 5-second timeout value.
For HTTP Status 408(Request Timeout) and 504(Gateway Timeout) responses, please implement retry processing using an exponential backoff strategy (exponentially increasing wait time for each retry - 1, 2, 4, 8 ...).

When calling the Check Possession Verification Code API, you must include input validation logic to ensure the API is not called if the verification_code value is empty.

Basic Information

POST /sms-sender/v3.2/occupancy_auth/verify_code
Host:
   https://api.gate8.com (SANDBOX)
   https://api.onstove.com (LIVE)
Content-Type: application/json

Request

Header

Name	Type	Required	Default Value	Example	Description
Authorization	String	Y	-	Bearer	Platform API Access Token (API AccessToken)[Authentication → Server] - Game (service) identification is derived from the `sid` of the token. - Web usage locations such as the official website also use this token after issuance.
Content-Type	String	Y	-	application/json	Resource media type
caller-id	String	Y	-	STOVE_GAME_ID	API caller information - Game ID registered in Partners * For monitoring / caller identification, not for game (service) identification
caller-detail	String	N	-	f248a284-7e61-4dcf-a111-a394050e9555	API caller UUID, for API call monitoring

Body

Name	Type	Required	Default Value	Example	Description
channel	String	Y	-	sms	Verification channel - `sms` : Mobile (SMS) possession verification - `email` : Email possession verification * Enter the same value as the channel that requested the verification code
to	String	Y	-	+821012345678	Verification target (format determined by `channel` ) - `channel=sms` : Phone number (E.164 format, including `+` and country code) - Automatic correction if '0' is entered incorrectly for a Korean phone number (+8201012345678 → +821012345678) - `channel=email` : Email address (e.g., user@example.com) * Enter the same value as the target that requested the verification code
verification_code	String	Y	-	123456	Verification code entered by the user (`sms` 6 digits / `email` 4 digits) - Verification code delivered via SMS or Email

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 data (delivered upon successful verification)

Value

Name	Type	Required	Default Value	Example	Description
possession_key	String	Y	-	SxrotG1lF454irWaWn0bIu7W4N/XRFM9	Verification identification key, delivered upon successful verification code check - Returns the same key value when requested for the same target (phone number / email) - The key value differs when the channel (`sms` / `email`) differs

Sample

Request

// Check possession verification code
curl -L -X POST 'https://api.gate8.com/sms-sender/v3.2/occupancy_auth/verify_code' \
-H 'Content-Type: application/json' \
-H "Caller-Id: {{caller-id}}" \
-H 'Caller-Detail: f248a284-7e61-4dcf-a111-a394050e9555' \
-H 'Authorization: Bearer {{API accessToken}}' \
-d '{
    "channel":"sms",
    "to":"+821012345678",
    "verification_code":"123456"
}'

Response

// Success
{
    "code": 0,
    "message": "OK",
    "value": {
        "possession_key": "SxrotG1lF454irWaWn0bIu7W4N/XRFM9"
    }
}

// Failure - verification code mismatch
{
    "code": 70103,
    "message": "verification fail"
}

// Failure - no verification code issued (expired / not issued / invalidated after 5 incorrect attempts)
{
    "code": 70104,
    "message": "no verification code"
}

Return Code

Please check and handle API errors on the server side

The front-end should only expose success or verification failure

HTTP Status code	Code	Message	Description	Responsible Party
200	0	OK	Success	API Caller (Server)
200	70100	invalid parameter	Input parameter error - Check and correct input parameters	API Caller (Server)
200	70103	verification fail	Verification code mismatch - Response when the entered verification code does not match the stored one - User re-entry processing (retry possible within validity period, invalidated upon reaching 5 attempts)	end user
200	70104	no verification code	No verification code issued, resend required - Response when verification code is expired / not issued, or completely invalidated due to 5 incorrect attempts - Guide user to resend (re-request) verification code	end user
200	70109	policy not registered	Unregistered policy - Inquire with platform manager	Platform Manager
200	70110	invalid phone number format	Phone number format error (`channel=sms`)	API Caller (Server)
200	70115	unsupported channel	Unsupported / inactive channel	API Caller (Server)
200	70116	invalid email format	Email format error (`channel=email`)	API Caller (Server)
200	70199	internal server error	Internal server error - Contact the platform manager	Platform Manager
401	40100 40101 40102 40103 40104 40106 40302 50000	-	Common token error - Check and modify platform authentication token (API AccessToken)	API Caller (Server)
408	40800	-	Request Timeout - Handle API call retries	API Caller (Server)
504	50400	-	Gateway Timeout - Handle API call retries	API Caller (Server)

Precautions when using possession_key

possession_key always returns the same value for the same target (mobile number / email), so it can be used to determine whether a verification target is duplicated within a game.
If the channel is different, the key value is also different. Even for the same user, the possession_key for SMS and Email are different values, so please manage them in the form of (guid, channel, possession_key).
possession_key should not be transmitted or exposed externally, and please encrypt and store it when saving to the game server.
Do not leave the verification target (to) or the verification code (verification_code) in logs. If unavoidable, to should be masked (+8210****5678, us**@ex****.com) and verification_code should not be recorded under any circumstances.