> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/tools/webshop.md).

# 웹샵 연동 가이드

<figure><img src="/files/fTKMZtAHFgv89CCQrNOZ" alt=""><figcaption></figcaption></figure>

### 1. 사용자 정보 연동

<a href="/pages/cTEDZ2HycCC1VsqTvTJk" class="button primary">상세 규격 보기</a>

<mark style="color:$info;">**\[선택]**</mark> 게임 내에서 원웹샵으로 이동하는 경로를 노출할 수 있습니다.

이동 URL에 사용자의 게임ID와 서버 정보를 포함하면, 원웹샵 진입 시 원스토어 로그인 상태와 구매 입력 정보가 자동 적용되어 바로 구매를 진행할 수 있습니다.

<details>

<summary>적용 예시</summary>

<figure><img src="/files/Hlhtm4PNZHg6YzahNcTK" alt=""><figcaption></figcaption></figure>

</details>

{% hint style="warning" %}
게임의 개인정보처리방침에 따라 게임ID가 개인정보에 해당할 경우, 개인정보 3자 제공 동의 과정 등을 추가해야할 수 있습니다.
{% endhint %}

### 2. 서버 리스트 연동 <a href="#id-2" id="id-2"></a>

<a href="/pages/ot9ZonGLBYTAoyFKGT7B" class="button primary">상세 규격 보기</a>

<mark style="color:$primary;">**\[필수]**</mark> 사용자가 원웹샵 상세 화면에 진입 시, 실시간으로 게임 서버 목록을 조회하여 노출합니다.

{% hint style="info" %}
아이템을 특정 서버로 지급해야 하는 경우, 개발사는 서버 목록 조회 API를 제공해야 합니다. \
API는 원웹샵 상세 화면에서 실시간으로 호출되며, 사용자가 서버를 선택해 구매하면 서버 정보가 PNS로 함께 전달됩니다.

단, 서버 목록은 타이틀 등록 시 `개발자센터 > 웹샵 > 기본정보 > 구매입력정보` 를 **구매식별자 + 서버**로 설정한 경우에만 사용자에게 표시됩니다.
{% endhint %}

<details>

<summary>적용 예시</summary>

<figure><img src="/files/ahCeStCAlJlZN0wq7p3D" alt=""><figcaption></figcaption></figure>

</details>

### 3. 유효성 검증  <a href="#id-3" id="id-3"></a>

<a href="/pages/Ldqaq9SSkPQrBCZvsK1j" class="button primary">상세 규격 보기</a>

<mark style="color:$primary;">**\[필수]**</mark> 사용자가 입력한 게임ID와 서버 정보의 유효성을 확인하고,해당 아이템의 구매 가능 여부를 검증합니다.

* 게임 ID는 아이템을 지급받을 최종 대상(유저/캐릭터)을 식별하는 값이며, 웹샵에서는 serviceUserId로 전달됩니다.\
  \&#xNAN;*<mark style="color:$info;">(게임 구조에 따라 UID 또는 캐릭터 ID 등으로 사용될 수 있습니다.)</mark>*

### 4. PNS (Payment Notification Service)

<a href="/pages/oRU887QZeredzPY8ym9m#pns" class="button primary">상세 규격 보기</a>

<mark style="color:$primary;">**\[필수]**</mark> 사용자가 결제를 완료하면, 결제 결과와 관련 결제 정보를 PNS 알림으로 게임 서버에 전달합니다.

PNS는 상용과 Sandbox 결제 환경을 모두 지원합니다.

### 5. 구매 확인 <a href="#id-5" id="id-5"></a>

<a href="/pages/oRU887QZeredzPY8ym9m#purchase" class="button primary">상세 규격 보기</a>

<mark style="color:$primary;">**\[필수]**</mark> 아이템이 정상적으로 지급되었음을 확인하기 위해 구매확인 처리는 반드시 진행해야 합니다.

구매확인은 목적에 따라 두 가지 API 중 하나를 사용할 수 있습니다.

<table><thead><tr><th width="203.41845703125">API</th><th>상세</th></tr></thead><tbody><tr><td>consumePurchase</td><td><ul><li>일반적으로 사용되는 구매확인 방식입니다.</li><li>처리 후 사용자는 <strong>동일 상품을 다시 구매할 수 있습니다.</strong></li></ul></td></tr><tr><td>acknowledgePurchase</td><td><ul><li>일회성 상품에 사용합니다.</li><li>처리 후 사용자는 <strong>동일 상품을 재구매할 수 없습니다.</strong></li></ul></td></tr></tbody></table>

{% hint style="warning" %}
**주의사항**

* 아이템 지급 후에는 반드시 구매확인을 처리해야 합니다.
* 구매확인이 3일 이내 완료되지 않으면, 아이템이 정상적으로 지급되지 않은 것으로 판단하여 해당 구매는 자동 취소됩니다.
* 구매확인이 완료되기 전까지 사용자는 동일한 아이템을 다시 구매할 수 없습니다.
  {% endhint %}

{% hint style="success" %}
**`getUnconfirmedPurchases` API를 통해 구매확인이 처리되지 않은 내역을 조회할 수 있습니다.**

안정적인 결제 처리를 위해 해당 API 활용을 권장드립니다.

* 상세 가이드는 [getUnconfirmedPurchases](/dev/tools/billing/v21/serverapi.md#getunconfirmedpurchases) 문서를 참고해주세요.
  {% endhint %}

### TIP. 웹샵 적용 가이드&#x20;

{% hint style="info" %}
원웹샵 연동이 완료되었다면, 실제 서비스 적용 시 **인앱결제 상점과의 배치 원칙, 올바른 진입 동선, 사용자 경험(UX), 운영 시 유의사항**을 반드시 확인해야 합니다.

* [**인앱결제 상점과 웹샵의 올바른 배치**](/dev/webshop/implementation.md#id-2)
* [**웹샵 상점 눌렀을때 올바른 동선**](/dev/webshop/implementation.md#id-3)
* [**사용자 경험 최적화 팁**](/dev/webshop/implementation.md#id-4)
* [**웹샵 상세 페이지 활용하기**](/dev/webshop/implementation.md#id-5)
* [**구매 횟수 제한 처리**](/dev/webshop/implementation.md#id-6)
  {% endhint %}