> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/contents/recommended/npay.md).

# Npay 주문형 연동하기

본 가이드는 스킨을 자체 제작하는 헤드리스를 위한 가이드 입니다.

### 네이버페이 설정 경로

샵바이 > 설정 > 네이버페이 설정 메뉴에서 확인하세요.

### 네이버페이 주문형 안내

네이버페이 주문형은 v1, v2로 구성됩니다. v1은 기존에 제공하던 방식으로 2027년 6월에 네이버페이의 지원이 종료됩니다. v2는 이번에 새롭게 업그레이드한 버전으로 템플릿형과 커스텀형 2가지로 구성됩니다. 

v1을 사용하는 상점들은 v2로 변경해 주셔야 합니다. v2로 변경 후 1주일 경과 시, v1 옵션으로 되돌아가실 수 없습니다.

<table><thead><tr><th width="245">구분</th><th>v1</th><th>v2</th></tr></thead><tbody><tr><td>지원기간</td><td>2027년 1월부터 신규지원 종료<br>2027년 5월까지만 기존상점 지원</td><td>2026년도 부터 지원</td></tr><tr><td>기능</td><td>제공 스타일 고정</td><td>템플릿형, 커스텀형 2가지 제공<br>스킨 환경에 따라 반응형으로 노출</td></tr><tr><td>버전 선택 노출 조건</td><td>기존 설정한 상점에게만 노출<br>한번도 설정하지 않은 상점에게는 미노출</td><td>기존 설정 유/무 관계없이 모두 노출</td></tr></tbody></table>

### 아래 도움말 확인하는 방법

\[v1] 표기된 안내는, 네이버페이 설정의 v1에 해당합니다. v1 사용자께서는 2027년 12월까지 v2로 변경해 주셔야합니다. v2로 변경후 1주일 경과시, v1로 되돌아가실 수 없으니 변경시 참고부탁드립니다.

\[v2] 표기된 안내는 네이버페이 설정의 v2에 해당합니다. v2는 템플릿과 커스텀형이 있으니 구분하여 확인이 필요합니다.

### \[v1] Npay 구매 버튼 스크립트

플랫폼 유형에 알맞은 스크립트를 선택해 헤더 영역에 추가하세요

{% code overflow="wrap" %}

```javascript
<!-- mobile -->
<script type="text/javascript" src="https://pay.naver.com/customer/js/mobile/naverPayButton.js"></script>

<!-- pc -->
<script type="text/javascript" src="https://pay.naver.com/customer/js/naverPayButton.js"></script>
```

{% endcode %}

### \[v1] Npay 구매 버튼 옵션 설정

옵션의 종류를 확인하고 알맞은 값을 추가하세요

> 네이버에서제공하는 스크립트를 분석해 작성한 내용입니다.
>
> 업데이트 시점에 따라 내용이 달라질 수 있으니 정확한 옵션에 대한 정보는 하기 스크립트를 확인하세요
>
> * PC : <https://pay.naver.com/customer/js/innerNaverPayButton.js?site_preference=normal&478465>\
>   문서 작성 시점 버전 : 1.3
> * MOBILE : <https://pay.naver.com/customer/js/mobile/innerNaverPayButton.js?site_preference=normal&478465>\
>   문서 작성 시점 버전 : 1.1

```javascript
// mobile
window.naver.NaverPayButton.apply({
    EMBED_ID: 'naver-pay',
    BUTTON_KEY: `${buttonKey}`,
    TYPE: 'MA',
    COLOR: 1,
    COUNT: 2,
    ENABLE: 'Y',
    BUY_BUTTON_HANDLER: {handleBuyButtonClick},
    WISHLIST_BUTTON_HANDLER: {handleWishListButtonClick},
  });
  
// pc
window.naver.NaverPayButton.apply({
    EMBED_ID: 'naver-pay',
    BUTTON_KEY: `${buttonKey}`,
    TYPE: 'A',
    COLOR: 1,
    COUNT: 1,
    ENABLE: 'Y',
    BUY_BUTTON_HANDLER: {handleBuyButtonClick},
    WISHLIST_BUTTON_HANDLER: {handleWishListButtonClick},
  });
  
```

* EMBED\_ID : `Npay 구매` 버튼 노출 할 영역의 `id` 값을 입력하세요.\
  예시)

{% code overflow="wrap" %}

```javascript
<!-- EMBED_ID: 'naver-pay' -->
<div id="naver-pay"></div>
```

{% endcode %}

* BUTTON\_KEY : 네이버에서 전달받은 버튼 생성키
  * `관리자 > 설정 > 네이버페이 설정 > 네이버페이 주문형 > 버튼 인증키` 에 입력한 값을 [GET /order-configs 주문 설정 값 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderConfiguration/get-order-configuration) API로 확인할 수 있습니다.\
    응답 값 중 `naverPay.buttonKey`를 사용하시면 됩니다.
* TYPE : 플랫폼 유형에 따라 다르게 설
  * PC : A \~ G
    * F와 G를 설정하는 경우 스크립트 옵션을 확인하세요\ <mark style="background-color:yellow;">F를 설정하는 경우 COLOR: 1, COUNT: 2 만 유효</mark>\ <mark style="background-color:yellow;">G를 설정하는 경우 COLOR: 1, COUNT: 1 만 유효</mark>
    * **샵바이 기본 스킨**에서는 `A`를 기본으로 사용합니다.<br>

      <div align="left"><figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FJ1fY9S29vJQrk5b0MkxC%2Fimage.png?alt=media&amp;token=de93e211-3c96-4731-8f59-2ae616fbe827" alt="" width="563"><figcaption></figcaption></figure></div>
  * MOBILE : MA, MB
    * **샵바이 기본 스킨**에서는 `MA`를 기본으로 사용합니다.<br>

      <div align="left"><figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FYR43B9mpX6akOwqIpv7V%2Fimage.png?alt=media&amp;token=7d2a711b-c93f-44b0-a846-4f5f1dcef45f" alt="" width="562"><figcaption></figcaption></figure></div>

    * COLOR : 버튼 모음의 색 설정. 1 혹은 2 설정 가능
      * **샵바이 기본 스킨**에서는 `1`를 기본으로 사용합니다.<br>

    * COUNT : 버튼 개수 설정. 구매하기 버튼만 있으면 1, 찜하기 버튼도 있으면 2를 입력
      * **샵바이 기본 스킨**에서는 `2`를 기본으로 사용합니다.
        * 단, **장바구니 페이지**에서는 **1**로 고정해서 사용합니다. 찜하기 기능을 사용하지 않습니다.<br>

    * ENABLE : 버튼 활성화 여부를 `Y` 혹은 `N` 으로 설정. 품절 등의 이유로 버튼 모음을 비활성화할 때에는 "N" 입력<br>

    * BUY\_BUTTON\_HANDLER : `NPay 구매` 버튼 클릭 시 호출하는 핸들러
      * 핸들러 안에서 2가지 API 를 호출해야 합니다.
        1. [PUT /payments/naver/validate 네이버페이 상품구매 검증하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/put-payments-naver-validate) API 로 Npay로 구매가능한 상품인지 확인합니다.
        2. [POST /payments/naver/ordersheet 네이버페이 주문서 생성하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/post-payments-naver-ordersheet)\
           1번에서 호출한 `검증 API` 응답 값이 `true` 인 경우에만 Npay 주문서를 생성하시면 됩니다.
           * `clientReturnUrl` 은 주문 실패 혹은 뒤로가기 시 리다이렉트 되는 주소로 `Npay`의 `backUrl`로 설정됩니다. 샵바이 기본 스킨에서는 `location.href` 로 설정합니다.<br>

    * WISHLIST\_BUTTON\_HANDLER: `찜` 하기 버튼 클릭 시 호출하는 핸들러
      * [POST /payments/naver/wish-list 네이버페이 찜 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/post-payments-naver-wish-list) API 를 호출해 `찜` 기능을 구현할 수 있습니다.

### \[v2] 네이버페이 템플릿형 옵션

템플릿형은 v2에만 해당되며, 네이버페이에서 제공하는 형태를 선택할 수 있습니다.&#x20;

* 네이버페이 구매 버튼: 필수입니다. 선택을 해제할 수 없습니다. 상품상세, 장바구니 화면 모두 노출됩니다.
* 네이버쇼핑 찜하기 버튼: 선택입니다. 선택 해제시, 스킨에 미노출됩니다. 상품상세 화면에만 노출됩니다.
* 네이버 톡톡 버튼: 선택입니다. 선택 해제시, 스킨에 미노출됩니다. 상품상세 화면에만 노출됩니다.
* 이벤트/혜택 메시지: 선택입니다. 선택 해제시, 스킨에 미노출됩니다. 메시지 내용은 네이버페이 관리자가 관리하는 내용으로 판매자가 입력하거나 선택할 수 없습니다. 상품상세, 장바구니 화면 모두 노출됩니다.
* 혜택 코치마크: 선택입니다. 선택 해제시, 스킨에 미노출됩니다. 메시지 내요은 네이버페이 관리자가 관리하는 내용으로 판매자가 입력하거나 선택할 수 없습니다. 상품상세, 장바구니 화면 모두 노출됩니다.

### \[v2] 네이버페이 색상 옵션

템플릿형은 색상을 선택할 수 있습니다.

* 녹색: 녹색으로 구성된 네이버페이 템플릿을 사용할 수 있습니다.
* 흰색: 흰색으로 구성된 네이버페이 템플릿을 사용할 수 있습니다.