# Type1 대조용 (이미 본인인증이 등록된 회원 대조)
https://accounts.onstove.com/verification?type=COMPARE_IDENTIFY&state={state}&redirect_url={redirect_url}&lang=ko

# Type1 최초 등록용 (본인인증 미등록 회원)
https://accounts.onstove.com/verification?type=STORAGE_IDENTIFY&state={state}&redirect_url={redirect_url}&lang=ko

# Type2 SDI 발급 (CP_GAME 으로 발급된 state)
https://accounts.onstove.com/verification?type=COMPARE_IDENTIFY&state={state}&redirect_url={redirect_url}

##### Troubleshooting

| Response code | Situation | Resolution |
|---|---|---|
| 91030 | Wrong Request — Missing required parameter or invalid value | Check the values in the request Body for `service` / `platform_type` / `cert_type` / `game_id` values. |
| 91031 | Not Verified — Result inquiry called before identity verification is complete | Verify that the user has completed the verification on the identity verification page, then try again. |
| 93000 | Redis compare data is null — state expired (10 minutes) / invalid state / state already queried via one-time API | Obtain a new simKey immediately before entering the page. |
| 40000 / 40101 / 40103 | API Access Token / User Access Token authentication error | Refer to the Authentication menu → Server Troubleshooting. Retry after reissuing the token. |

> [!warning]
> **Precautions for implementing Type2 SDI receiving endpoint**  
> · Stove considers the transmission complete when the game server responds with HTTP `2xx`. Since it **retries on `5xx` / `4xx` responses**, SDI may be received redundantly with the same `state`. Please ensure idempotency (prevention of duplicate storage) at the `state` level.  
> · The endpoint must operate on **HTTPS + TLS 1.2 or higher**.  
> · **Infrastructure ACL registration** is required for Stove → game server calls. Please provide the game server domain/IP to the assigned technical PM.  
> · Even for the same user, **different SDIs are generated for Sandbox / Live environments**, so separate storage by environment is required.

> [!info]
> **SDI is personal information**  
> Do not record it in logs as-is; apply masking or exclusion. When a user withdraws from the game, the mapped SDI must be deleted.

##### Sample Code

<p style="color:#314158;font-family:'Spoqa Han Sans Neo';font-size:16px;font-weight:400;line-height:26px;letter-spacing:-0.48px;">This is an example of calling Type1 comparison simKey issuance (<code>POST /sim/v1/compare</code>) and multi-use result inquiry (<code>GET /sim/v1/compare/check</code>). <br>For Type1 initial registration, change the endpoint to <code>/sim/v1/cert</code>, and for Type2 SDI, replace <code>platform_type</code> with <code>CP_GAME</code>.</p>

> [!warning]
> **Please replace the Base URL according to the environment (Live/Sandbox)**  
> In production environments, it is recommended to separate it into environment variables (e.g., `STOVE_API_BASE_URL`) or framework configuration files and inject it per environment instead of hardcoding.```java
    // Java 25 LTS — java.net.http.HttpClient + Jackson(ObjectMapper)
    import com.fasterxml.jackson.databind.JsonNode;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import java.net.URI;
    import java.net.URLEncoder;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.nio.charset.StandardCharsets;
    import java.time.Duration;
    import java.util.Map;

    ObjectMapper mapper = new ObjectMapper();
    String baseUrl = "https://api.onstove.com";
    String serviceId = "STOVE_GAME";
    String callerId = serviceId + "_SERVER";

    try (HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build()) {

        // 1) simKey(state) 발급 (Type1 대조용)
        String issueBody = mapper.writeValueAsString(Map.of(
                "service", "STOVE",
                "platform_type", "PC_WEB_CHECK",
                "cert_type", "SELF",
                "game_id", serviceId));

        HttpRequest issueReq = HttpRequest.newBuilder(URI.create(baseUrl + "/sim/v1/compare"))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + userAccessToken)
                .header("caller-id", callerId)
                .POST(HttpRequest.BodyPublishers.ofString(issueBody))
                .build();
        HttpResponse<String> issueRes = client.send(issueReq, HttpResponse.BodyHandlers.ofString());
        JsonNode issueData = mapper.readTree(issueRes.body());
        if (issueData.path("code").asInt() != 0) {
            // 트러블슈팅 표 참고 (91030 등)
            throw new IllegalStateException("simKey issue failed: " + issueData.path("code"));
        }
        String state = issueData.path("value").asText();

        // 2) 본인인증 결과 조회 (다회용)
        // 이용자가 웹에서 본인인증을 마친 시점 이후에 호출
        String encodedState = URLEncoder.encode(state, StandardCharsets.UTF_8);
        HttpRequest verifyReq = HttpRequest.newBuilder(
                URI.create(baseUrl + "/sim/v1/compare/check?state=" + encodedState))
                .header("caller-id", callerId)
                .GET()
                .build();
        HttpResponse<String> verifyRes = client.send(verifyReq, HttpResponse.BodyHandlers.ofString());
        JsonNode verifyData = mapper.readTree(verifyRes.body());
        if (verifyData.path("code").asInt() == 0) {
            // 본인인증 완료 — 후속 처리 진행
        } else {
            // 트러블슈팅 표 참고 (91031 / 93000 등)
        }
    }

// .NET 10 LTS — System.Net.Http.HttpClient (표준 라이브러리)
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var baseUrl = "https://api.onstove.com";
var serviceId = "STOVE_GAME";
var callerId = $"{serviceId}_SERVER";

using var client = new HttpClient { BaseAddress = new Uri(baseUrl) };
client.DefaultRequestHeaders.Add("caller-id", callerId);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", userAccessToken);

// 1) simKey(state) 발급 (Type1 대조용)
var issueRes = await client.PostAsJsonAsync("/sim/v1/compare", new
{
    service = "STOVE",
    platform_type = "PC_WEB_CHECK",
    cert_type = "SELF",
    game_id = serviceId,
});
var issueData = await issueRes.Content.ReadFromJsonAsync<JsonElement>();
if (issueData.GetProperty("code").GetInt32() != 0)
{
    // 트러블슈팅 표 참고 (91030 등)
    throw new InvalidOperationException($"simKey issue failed: {issueData.GetProperty("code")}");
}
var state = issueData.GetProperty("value").GetString();

// 2) 본인인증 결과 조회 (다회용)
// 이용자가 웹에서 본인인증을 마친 시점 이후에 호출
var encodedState = Uri.EscapeDataString(state);
var verifyRes = await client.GetAsync($"/sim/v1/compare/check?state={encodedState}");
var verifyData = await verifyRes.Content.ReadFromJsonAsync<JsonElement>();
if (verifyData.GetProperty("code").GetInt32() == 0)
{
    // 본인인증 완료 — 후속 처리 진행
}
else
{
    // 트러블슈팅 표 참고 (91031 / 93000 등)
}

=== "Node.js (24 LTS)"
```javascript
// Node.js 24 LTS — Built-in fetch (ESM)
const baseUrl = 'https://api.onstove.com';
const serviceId = 'STOVE_GAME';
const callerId = `${serviceId}_SERVER`;

// 1) Issue simKey(state) (for Type1 comparison)
const issueRes = await fetch(`${baseUrl}/sim/v1/compare`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${userAccessToken}`,
    'caller-id': callerId,
  },
  body: JSON.stringify({
    service: 'STOVE',
    platform_type: 'PC_WEB_CHECK',
    cert_type: 'SELF',
    game_id: serviceId,
  }),
});
const issueData = await issueRes.json();
if (issueData.code !== 0) {
  // Refer to the troubleshooting table (91030, etc.)
  throw new Error(`simKey issue failed: ${issueData.code}`);
}
const state = issueData.value;

// 2) Verify identity result (multi-use)
// Called after the user completes identity verification on the web
const encodedState = encodeURIComponent(state);
const verifyRes = await fetch(`${baseUrl}/sim/v1/compare/check?state=${encodedState}`, {
  method: 'GET',
  headers: {
    'caller-id': callerId,
  },
});
const verifyData = await verifyRes.json();
if (verifyData.code === 0) {
  // Identity verification complete — proceed with follow-up processing
} else {
  // Refer to the troubleshooting table (91031 / 93000, etc.)
}


<div style="margin-top:10px;"></div>

### Possession Verification (SMS/Email)

<p style="color:#314158;font-family:'Spoqa Han Sans Neo';font-size:16px;font-weight:400;line-height:26px;letter-spacing:-0.48px;">Possession verification is structured so that the game server calls the two steps of the STOVE possession verification API (Send → Verify), while the game client is only responsible for the input and result screen UX. SMS and Email use <strong>the same endpoint</strong> and are distinguished only by the <code>channel</code> value. There is no SDK call, and all external communication occurs between the game server and the STOVE API, so game server implementation is central. <br>Refer to the troubleshooting table if you need detailed meanings of response codes.</p>

##### Prerequisites

=== "C#"
```csharp
// System.Net.Http.HttpClient (standard library)
// Sample for calling the occupancy auth APIs in order: send code -> verify code.
// Each API is organized into STEP 1-5.

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading.Tasks;

public static class OccupancyAuthSample
{
    // Base URL : Live https://api.onstove.com / Sandbox https://api.gate8.com
    private static readonly HttpClient Client = new()
    {
        BaseAddress = new Uri("https://api.onstove.com"),
    };

    // ==============================================================================
    // [API 1] Send verification code  POST /sms-sender/v3.2/occupancy_auth/send_code
    // ==============================================================================
    public static async Task<JsonElement> SendCodeAsync(string apiAccessToken, string channel, string to, string locale)
    {
        // STEP 1. Set variables
        var path = "/sms-sender/v3.2/occupancy_auth/send_code";
        var callerId = "STOVE_GAME_ID";                               // (required) Game ID registered in Partners
        var callerDetail = "f248a284-7e61-4dcf-a111-a394050e9555";    // (optional) Caller UUID, for monitoring

        // STEP 2. Prepare request parameters (Body)
        var body = new Dictionary<string, string>
        {
            ["channel"] = channel,   // (required) Auth channel : "sms" | "email"
            ["to"] = to,             // (required) Auth target : sms = "+821012345678" / email = "user@example.com"
        };
        if (channel == "email")
        {
            body["locale"] = locale; // (optional) Email-only language : "ko" | "en" (defaults to "en")
        }

        // STEP 3. Build the request (Header)
        using var request = new HttpRequestMessage(HttpMethod.Post, path)
        {
            Content = JsonContent.Create(body),                                              // (required) Content-Type: application/json
        };
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiAccessToken); // (required) API Access Token (see /docs/stove/guide/authentication#server)
        request.Headers.Add("caller-id", callerId);                                          // (required)
        request.Headers.Add("caller-detail", callerDetail);                                  // (optional)

        // STEP 4. Call the API
        var response = await Client.SendAsync(request);

        // STEP 5. Handle the response
        if (!response.IsSuccessStatusCode)
        {
            // 401 : reissue the token / 408, 429, 504 : retry with exponential backoff
            throw new InvalidOperationException($"send_code http {(int)response.StatusCode}");
        }
        var result = await response.Content.ReadFromJsonAsync<JsonElement>();
        var code = result.GetProperty("code").GetInt32();                 // Response code (0 = success)
        if (code != 0)
        {
            // 70101 resend limit / 70105 daily limit / 70107 unsupported country / 70115 unregistered channel ... (see the troubleshooting table)
            throw new InvalidOperationException($"send_code failed: code={code}");
        }
        var codeLength = result.GetProperty("value").GetProperty("code_length").GetInt32();  // Code length (sms 6 / email 4)
        var expiresIn = result.GetProperty("value").GetProperty("expires_in").GetInt32();    // Time to live in seconds (sms 180 / email 600)
        // Pass codeLength and expiresIn to the game client to set the input length and the timer.
        return result;
    }

    // ==============================================================================
    // [API 2] Verify code  POST /sms-sender/v3.2/occupancy_auth/verify_code
    // ==============================================================================
    public static async Task<string> VerifyCodeAsync(string apiAccessToken, string channel, string to, string verificationCode)
    {
        // STEP 1. Set variables
        var path = "/sms-sender/v3.2/occupancy_auth/verify_code";
        var callerId = "STOVE_GAME_ID";
        var callerDetail = "f248a284-7e61-4dcf-a111-a394050e9555";

        // STEP 2. Prepare request parameters (Body)
        // NOTE: Do not call the API when verification_code is empty. Validate blank and length first.
        if (string.IsNullOrWhiteSpace(verificationCode))
        {
            throw new ArgumentException("verification_code is empty");
        }
        var body = new Dictionary<string, string>
        {
            ["channel"] = channel,                        // (required) Same channel as the send request
            ["to"] = to,                                  // (required) Same auth target as the send request
            ["verification_code"] = verificationCode,     // (required) Code entered by the user (sms 6 digits / email 4 digits)
        };

        // STEP 3. Build the request (Header)
        using var request = new HttpRequestMessage(HttpMethod.Post, path)
        {
            Content = JsonContent.Create(body),
        };
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiAccessToken);
        request.Headers.Add("caller-id", callerId);
        request.Headers.Add("caller-detail", callerDetail);

        // STEP 4. Call the API
        var response = await Client.SendAsync(request);

        // STEP 5. Handle the response
        if (!response.IsSuccessStatusCode)
        {
            // 401 : reissue the token / 408, 504 : retry with exponential backoff
            throw new InvalidOperationException($"verify_code http {(int)response.StatusCode}");
        }
        var result = await response.Content.ReadFromJsonAsync<JsonElement>();
        var code = result.GetProperty("code").GetInt32();
        if (code == 70103)
        {
            // Code mismatch -> ask the user to re-enter (all codes are invalidated after 5 failures)
            return null;
        }
        if (code == 70104)
        {
            // No issued code (expired or invalidated) -> ask the user to request a resend
            return null;
        }
        if (code != 0)
        {
            throw new InvalidOperationException($"verify_code failed: code={code}");
        }
        // Verified. possession_key can be used to check whether the auth target is a duplicate. (optional)
        return result.GetProperty("value").GetProperty("possession_key").GetString();
    }
}

// net/http + encoding/json (standard library)
// Sample for calling the occupancy auth APIs in order: send code -> verify code.
// Each API is organized into STEP 1-5.

package occupancyauth

import (
    "bytes"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "net/http"
)

// Base URL : Live https://api.onstove.com / Sandbox https://api.gate8.com
const baseURL = "https://api.onstove.com"

var httpClient = &http.Client{}

// Verify API response codes that require user guidance.
var (
    ErrCodeMismatch = errors.New("verification code mismatch") // 70103
    ErrCodeNotFound = errors.New("no verification code")       // 70104
)

// SendCodeResponse is the response of the send-code API.
type SendCodeResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Value   struct {
        Channel    string `json:"channel"`     // Sent channel
        CodeLength int    `json:"code_length"` // Code length (sms 6 / email 4)
        ExpiresIn  int    `json:"expires_in"`  // Time to live in seconds (sms 180 / email 600)
    } `json:"value"`
}

// VerifyCodeResponse is the response of the verify-code API.
type VerifyCodeResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Value   struct {
        PossessionKey string `json:"possession_key"`
    } `json:"value"`
}

// ==============================================================================
// [API 1] Send verification code  POST /sms-sender/v3.2/occupancy_auth/send_code
// ==============================================================================
func SendCode(ctx context.Context, apiAccessToken, channel, to, locale string) (*SendCodeResponse, error) {

    // STEP 1. Set variables
    url := baseURL + "/sms-sender/v3.2/occupancy_auth/send_code"
    callerID := "STOVE_GAME_ID"                            // (required) Game ID registered in Partners
    callerDetail := "f248a284-7e61-4dcf-a111-a394050e9555" // (optional) Caller UUID, for monitoring

    // STEP 2. Prepare request parameters (Body)
    body := map[string]string{
        "channel": channel, // (required) Auth channel : "sms" | "email"
        "to":      to,      // (required) Auth target : sms = "+821012345678" / email = "user@example.com"
    }
    if channel == "email" {
        body["locale"] = locale // (optional) Email-only language : "ko" | "en" (defaults to "en")
    }
    payload, err := json.Marshal(body)
    if err != nil {
        return nil, err
    }

    // STEP 3. Build the request (Header)
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Authorization", "Bearer "+apiAccessToken) // (required) API Access Token (see /docs/stove/guide/authentication#server)
    req.Header.Set("Content-Type", "application/json")        // (required)
    req.Header.Set("caller-id", callerID)                     // (required)
    req.Header.Set("caller-detail", callerDetail)             // (optional)

    // STEP 4. Call the API
    res, err := httpClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    // STEP 5. Handle the response
    if res.StatusCode != http.StatusOK {
        // 401 : reissue the token / 408, 429, 504 : retry with exponential backoff
        return nil, fmt.Errorf("send_code http %d", res.StatusCode)
    }
    var result SendCodeResponse
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        return nil, err
    }
    if result.Code != 0 {
        // 70101 resend limit / 70105 daily limit / 70107 unsupported country / 70115 unregistered channel ... (see the troubleshooting table)
        return nil, fmt.Errorf("send_code failed: code=%d", result.Code)
    }
    // Pass CodeLength and ExpiresIn in result.Value to the game client to set the input length and the timer.
    return &result, nil
}

// ==============================================================================
// [API 2] Verify code  POST /sms-sender/v3.2/occupancy_auth/verify_code
// ==============================================================================
func VerifyCode(ctx context.Context, apiAccessToken, channel, to, verificationCode string) (string, error) {

    // STEP 1. Set variables
    url := baseURL + "/sms-sender/v3.2/occupancy_auth/verify_code"
    callerID := "STOVE_GAME_ID"
    callerDetail := "f248a284-7e61-4dcf-a111-a394050e9555"

    // STEP 2. Prepare request parameters (Body)
    // NOTE: Do not call the API when verification_code is empty. Validate blank and length first.
    if verificationCode == "" {
        return "", errors.New("verification_code is empty")
    }
    body := map[string]string{
        "channel":           channel,          // (required) Same channel as the send request
        "to":                to,               // (required) Same auth target as the send request
        "verification_code": verificationCode, // (required) Code entered by the user (sms 6 digits / email 4 digits)
    }
    payload, err := json.Marshal(body)
    if err != nil {
        return "", err
    }

    // STEP 3. Build the request (Header)
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
    if err != nil {
        return "", err
    }
    req.Header.Set("Authorization", "Bearer "+apiAccessToken)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("caller-id", callerID)
    req.Header.Set("caller-detail", callerDetail)

    // STEP 4. Call the API
    res, err := httpClient.Do(req)
    if err != nil {
        return "", err
    }
    defer res.Body.Close()

    // STEP 5. Handle the response
    if res.StatusCode != http.StatusOK {
        // 401 : reissue the token / 408, 504 : retry with exponential backoff
        return "", fmt.Errorf("verify_code http %d", res.StatusCode)
    }
    var result VerifyCodeResponse
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        return "", err
    }
    switch result.Code {
    case 0:
        // Verified. possession_key can be used to check whether the auth target is a duplicate. (optional)
        return result.Value.PossessionKey, nil
    case 70103:
        // Code mismatch -> ask the user to re-enter (all codes are invalidated after 5 failures)
        return "", ErrCodeMismatch
    case 70104:
        // No issued code (expired or invalidated) -> ask the user to request a resend
        return "", ErrCodeNotFound
    default:
        return "", fmt.Errorf("verify_code failed: code=%d", result.Code)
    }
}

// Built-in fetch (ESM)
// Sample for calling the occupancy auth APIs in order: send code -> verify code.
// Each API is organized into STEP 1-5.

// No extra import is needed because the built-in fetch is used.
// (On Node.js below 18, a separate package such as "node-fetch" is required.)`import fetch from 'node-fetch';` is required.)

// Base URL : Live https://api.onstove.com / Sandbox https://api.gate8.com
const BASE_URL = 'https://api.onstove.com';

// ==============================================================================
// [API 1] Send verification code  POST /sms-sender/v3.2/occupancy_auth/send_code
// ==============================================================================
export async function sendCode(apiAccessToken, channel, to, locale) {

  // STEP 1. Set variables
  const url = `${BASE_URL}/sms-sender/v3.2/occupancy_auth/send_code`;
  const callerId = 'STOVE_GAME_ID';                              // (required) Game ID registered in Partners
  const callerDetail = 'f248a284-7e61-4dcf-a111-a394050e9555';   // (optional) Caller UUID, for monitoring

  // STEP 2. Prepare request parameters (Body)
  const body = {
    channel,   // (required) Auth channel : 'sms' | 'email'
    to,        // (required) Auth target : sms = '+821012345678' / email = 'user@example.com'
  };
  if (channel === 'email') {
    body.locale = locale;   // (optional) Email-only language : 'ko' | 'en' (defaults to 'en')
  }

  // STEP 3. Build the request (Header)
  const request = {
    method: 'POST',
    headers: {
      Authorization: "`Bearer ${apiAccessToken}`,   // (required) API Access Token (see /docs/stove/guide/authentication#server)
      'Content-Type': 'application/json',          // (required)
      'caller-id': callerId,                       // (required)
      'caller-detail': callerDetail,               // (optional)
    },
    body: JSON.stringify(body),
  };

  // STEP 4. Call the API
  const response = await fetch(url, request);

  // STEP 5. Handle the response
  if (!response.ok) {
    // 401 : reissue the token / 408, 429, 504 : retry with exponential backoff
    throw new Error("`send_code http ${response.status}`);
  }
  const result = await response.json();
  if (result.code !== 0) {
    // 70101 resend limit / 70105 daily limit / 70107 unsupported country / 70115 unregistered channel ... (see the troubleshooting table)
    throw new Error("`send_code failed: code=${result.code}`);
  }
  const { code_length: codeLength, expires_in: expiresIn } = result.value;
  // Use codeLength (sms 6 / email 4) and expiresIn (sms 180 / email 600) to set the input length and the timer.
  return { codeLength, expiresIn };
}

// ==============================================================================
// [API 2] Verify code  POST /sms-sender/v3.2/occupancy_auth/verify_code
// ==============================================================================
export async function verifyCode(apiAccessToken, channel, to, verificationCode) {

  // STEP 1. Set variables
  const url = "`${BASE_URL}/sms-sender/v3.2/occupancy_auth/verify_code`;
  const callerId = 'STOVE_GAME_ID';
  const callerDetail = 'f248a284-7e61-4dcf-a111-a394050e9555';

  // STEP 2. Prepare request parameters (Body)
  // NOTE: Do not call the API when verification_code is empty. Validate blank and length first.
  if (!verificationCode || verificationCode.trim() === '') {
    throw new Error('verification_code is empty');
  }
  const body = {
    channel,                                 // (required) Same channel as the send request
    to,                                      // (required) Same auth target as the send request
    verification_code: verificationCode,     // (required) Code entered by the user (sms 6 digits / email 4 digits)
  };

  // STEP 3. Build the request (Header)
  const request = {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiAccessToken}`,
      'Content-Type': 'application/json',
      'caller-id': callerId,
      'caller-detail': callerDetail,
    },
    body: JSON.stringify(body),
  };

  // STEP 4. Call the API
  const response = await fetch(url, request);

  // STEP 5. Handle the response
  if (!response.ok) {
    // 401 : reissue the token / 408, 504 : retry with exponential backoff
    throw new Error(`verify_code http ${response.status}`);
  }
  const result = await response.json();
  if (result.code === 70103) {
    // Code mismatch -> ask the user to re-enter (all codes are invalidated after 5 failures)
    return null;
  }
  if (result.code === 70104) {
    // No issued code (expired or invalidated) -> ask the user to request a resend
    return null;
  }
  if (result.code !== 0) {
    throw new Error(`verify_code failed: code=${result.code}`);
  }
  // Verified. possession_key can be used to check whether the auth target is a duplicate. (optional)
  return result.value.possession_key;
}


<div style="margin-top:70px;"></div>

## Frequently Asked Questions
---

<br />

<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q1. [Identity Verification] What is the difference between Type1 and Type2?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. Type1 is a CI-based identity verification method where the Stove platform stores and manages the CI itself to determine if the user is the same person and returns the result. <br>Up to 5 accounts (memberNo) can be linked to a single CI value.<br> Type2 is an SDI-based identification value provision method where the original CI is not stored on the Stove platform, and only the one-way encrypted SDI value is delivered to the CP server. <br>SDI value management is handled by each service provider (CP).</div></div>

</details>
<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q2. [Identity Verification] Should I choose the multi-use or single-use API when checking the results?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. If the flow ends after confirming the identity verification result, please use the single-use identity verification result check API (<code>DELETE /sim/v1/compare/expire</code>). <br>The state expires after the result check is complete. If you need to perform checks until the simKey (state) expires, use the multi-use result check API (<code>GET /sim/v1/compare/check</code>). <br>The validity period of the issued simKey (state) is 10 minutes from the initial issuance.</div></div>

</details>
<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q3. [Possession Verification] What are the validity period and resend limits for the verification code?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. It varies by channel. SMS has a 6-digit verification code with a 3-minute validity period, and Email has a 4-digit verification code with a 10-minute validity period (you can also check this via <code>value.code_length</code>·<code>value.expires_in</code> in the send response). <br>When requesting for the same target, all sent verification codes remain valid until the expiration time, and if even one verification code is successfully verified, all other codes are invalidated. <br>For resends based on the same game and same target, you can request up to 3 times per minute and 20 times per day for SMS, and 5 times per hour for Email.</div></div>

</details>
<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q4. [Possession Verification] How do I select between SMS and Email channels?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. Supported channels (SMS only / Email only / Both) are registered on the platform for each game, and you specify one of <code>channel</code> as <code>sms</code> / <code>email</code> when calling the API. <br>If you request an unregistered channel, it will return <code>70115</code> (unsupported channel), so please consult with your business manager in advance regarding the channels to use. <br>SMS has limited supported countries, and unsupported countries will return <code>70107</code>, but Email has no country restrictions. <br>For Email, the sending language is specified by <code>locale</code> (<code>ko</code> / <code>en</code>, defaults to <code>en</code> if not specified), and for SMS, it is automatically determined by the country code of the number.</div></div>

</details>
<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q5. [Possession Verification] What happens if I enter the verification code incorrectly multiple times?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. If the verification code is entered incorrectly 5 times for the same game and target, the verification code for that target will be completely invalidated (applies to both SMS and Email).<br>Requests for verification after invalidation will return <code>70104</code>(no verification code), so please guide the user to resend the verification code.<br>The failure count is reset if the verification succeeds once or if the verification code is resent.</div></div>

</details>
<details open style="margin:0 0 32px 0;border:1px solid #e3e6ea;border-radius:8px;overflow:hidden;">
<summary style="cursor:pointer;list-style:none;padding:14px 18px;background-color:#F8FAFC;font-size:16px;font-weight:600;color:#314158;">Q6. [Ownership Verification] How should I inform users about API errors?</summary>

<div style="padding:12px 18px;"><div style="font-size:15px;font-weight:400;color:#314158;line-height:1.7;">A. Please check and handle API errors on the server side, and avoid exposing response codes directly to the frontend.<br>If you must provide an error code to the user, please display it in the <strong>S + code</strong> format so that it is not recognized as a phone number. (e.g., <code>S70199</code>)
<div style="max-width:375px;margin:16px 0 4px 0;background:#FFFFFF;border:1px solid #CBD5E1;border-radius:16px;overflow:hidden;">
<div style="background:#314158;color:#FFFFFF;font-family:'Spoqa Han Sans Neo';font-size:15px;font-weight:700;line-height:22px;letter-spacing:-0.28px;text-align:center;padding:12px 16px;">Mobile phone number verification failed</div>

<div style="padding:20px;color:#314158;font-family:'Spoqa Han Sans Neo';font-size:14px;font-weight:400;line-height:22px;letter-spacing:-0.28px;text-align:center;word-break:keep-all;overflow-wrap:normal;">
The service is currently unavailable.<br>Please try again.
<p style="color:#314158;font-size:14px;line-height:22px;margin:12px 0 0 0;">If the problem persists, please contact customer support. (S70199)</p>

<div style="margin:16px auto 0 auto;width:60%;padding:8px 0;background:#6B7280;border-radius:18px;color:#FFFFFF;font-size:13px;line-height:22px;text-align:center;">Confirm</div>

</div>
</div>
</div></div>
</details>

<br><br>

<div style="display:flex;align-items:center;gap:8px;margin-bottom:4px;"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#6588F9" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" style="flex-shrink:0;"><rect x="3" y="5" width="18" height="14" rx="2.5"/><path d="m3.5 7.5 8.5 6 8.5-6"/></svg><span style="color:#314158;font-size:14px;">Would you like to contact us directly?&nbsp;<a href="mailto:stove.developers@smilegate.com" style="color:#314158;text-decoration:underline;">stove.developers@smilegate.com</a></span></div></div>