> 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).

# 네이버페이 주문형 설정

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

{% hint style="info" %} <mark style="color:red;">SDK v1은 2027년 6월 fade-out 예정입니다.</mark> 유예 기간 내에 SDK v2로 전환해 주시기 바랍니다.
{% endhint %}

{% hint style="info" %} <mark style="color:red;">**\[유의사항] 네이버페이 버튼 SDK v2 연동 도메인 안내**</mark>

SDK v2에서는 버튼 스크립트를 호출하는 쇼핑몰 도메인과 네이버페이에 등록된 연동 도메인이 같아야 버튼이 노출(활성화)됩니다.

※ 등록된 연동 도메인은 \[네이버페이센터 > 내 정보관리 > 가입정보 변경] 메뉴의 '쇼핑몰 URL' 항목에서 확인하실 수 있습니다.

**서브 도메인을 운영하는 상점 유의사항**

* 네이버페이 버튼 SDK v2부터는 **쇼핑몰 접속 도메인과 네이버페이에 등록된 '쇼핑몰 URL'이 같아야** 상품상세·장바구니 화면에 네이버페이 버튼이 노출됩니다.
  * 등록된 쇼핑몰 URL은 \[네이버페이센터 > 내 정보관리 > 가입정보 변경] 메뉴에서 확인하실 수 있습니다.
* **메인 도메인 외에 서브 도메인을 함께 운영하는 쇼핑몰**은 네이버페이에 등록되지 않은 도메인으로 접속한 화면에서 네이버페이 버튼이 보이지 않을 수 있습니다.
* 여러 도메인을 운영 중이라면 실제 고객이 접속하는 대표 도메인이 네이버페이 '쇼핑몰 URL'에 등록되어 있는지 미리 확인해 주세요. 혹은 네이버페이 정책 변경 일정에 따라 2027년 이후에 SDK v2를 적용해 주세요.
  {% endhint %}

### 네이버페이 주문형 설정 경로

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

### 네이버페이 주문형 노출 위치

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FPye6sSw4lsND7KQdhDiA%2F_Description-%E1%84%80%E1%85%B5%E1%84%87%E1%85%A9%E1%86%AB_5.png?alt=media&amp;token=8875e7c0-5f5f-4c8d-839d-afe5d9e055e0" alt="" width="563"><figcaption></figcaption></figure>

① 상품 상세 화면 : 네이버페이 버튼이 상품 상세 화면에 노출됩니다.

② 장바구니 화면 : 네이버페이 버튼이 장바구니 화면에 노출됩니다.

### 네이버페이 주문형 설정/관리

* 네이버페이를 쇼핑몰에서 결제 수단으로 사용하기 위해 필요한 설정값을 입력합니다. 사용 설정 전 네이버페이 신청이 완료되어 있어야 하며, 네이버페이 신청이 되어 있지 않으면 설정 내용은 저장되지만 실제로 결제가 진행되지 않습니다.
* 네이버페이로 결제한 주문의 정보를 네이버 측과 통신하기 위한 인증값을 입력합니다. 네이버페이 인증값이 정확하지 않은 경우 네이버페이로 결제가 정상적으로 진행되지 않으므로 입력 시 유의 바랍니다.

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FKnJLP0opSSsLyzMZ9rOi%2F_Description-%E1%84%80%E1%85%B5%E1%84%87%E1%85%A9%E1%86%AB_2.png?alt=media&amp;token=0477be93-f638-4a2e-9b13-7a23b761f1f8" alt="" width="563"><figcaption></figcaption></figure>

① 네이버 가맹점 ID : 네이버페이 가입 시 등록한 운영 쇼핑몰 ID를 입력합니다.

② 가맹점(연동) 인증키 : 네이버페이 가입 승인 시 부여받은 연동 인증키 값을 입력합니다.

③ 버튼(이미지) 인증키 : 네이버페이 가입 승인 시 부여받은 이미지 인증키 값을 입력합니다.&#x20;

### 네이버페이 SDK 버전 선택

쇼핑몰 상세 화면 및 장바구니 화면에 노출할 버튼 이미지 종류를 선택합니다.&#x20;

{% hint style="info" %} <mark style="color:red;">SDK v1은 2027년 6월부로 지원이 종료됩니다.</mark>&#x20;

유예 기간 내에 SDK v2로 전환해 주시기 바랍니다.
{% endhint %}

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FWhVDRaBYEsgL8ux52g6e%2F_Description-%E1%84%80%E1%85%B5%E1%84%87%E1%85%A9%E1%86%AB_4.png?alt=media&amp;token=20e0efcf-621e-40f9-a1c3-bfbb408e6b28" alt="" width="563"><figcaption></figcaption></figure>

<table><thead><tr><th width="245">구분</th><th>기존 SDK v1</th><th>신규 SDK v2</th></tr></thead><tbody><tr><td>지원기간</td><td>2027년 6월 fade-out</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 : <mark style="color:$danger;">2027년 6월부터 v1 지원이 종료됩니다.</mark> 유예 기간 내에 v2로 변경해야 합니다.

② v2 : 네이버페이에서 새롭게 지원하는 반응형 버전으로 템플릿형, 커스텀형으로 유형을 구분하여 이용할 수 있습니다. 최초로 네이버페이를 설정하는 쇼핑몰에는 v2 옵션만 노출됩니다. v1로 이미 설정된 쇼핑몰에는 v2 옵션이 추가로 노출됩니다. v1에서 v2로 변경 후 1주일 경과 시, v1 옵션은 미노출 처리됩니다.

### SDK 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 %}

### SDK 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 를 호출해 `찜` 기능을 구현할 수 있습니다.

### SDK v2 > 버튼 유형 선택

SDK v2에서 지원하는 버튼 유형을 선택할 수 있습니다.

| 구분          | 권장 크기                 | 비고                                                  |
| ----------- | --------------------- | --------------------------------------------------- |
| 너비 (width)  | 최소 200px \~ 최대 1280px | <p>200px 미만: 버튼이 잘려서 노출됨<br>1280px 초과: 좌우 여백 발생</p> |
| 높이 (height) | 150px                 | 이하로 설정 시 선택한 구성요소에 따라 버튼이 잘려서 노출될 수 있음              |

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FZPNvCkYiaQOVCTjB1PVj%2F_Description-%E1%84%80%E1%85%B5%E1%84%87%E1%85%A9%E1%86%AB_3.png?alt=media&amp;token=d140f678-9d48-4335-a763-b39ba82e57b4" alt="" width="563"><figcaption></figcaption></figure>

① 템플릿형 : 네이버페이에서 지원하는 템플릿으로 색상과 구성 요소를 선택할 수 있습니다.

② 커스텀형 : 스킨 수정에서 디자인을 커스텀할 수 있습니다.

### SDK v2 > 템플릿형 > 색상 선택

* 녹색(기본), 흰색 2가지 색상 중에서 선택할 수 있습니다.
* `colorTheme` 파라미터를 통해 버튼 색상을 선택할 수 있습니다.
* `enable: false` 설정 시 비활성화 상태로 표시됩니다.

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2FsHxxkK04IHLsjXuzylfc%2F_Description-%E1%84%80%E1%85%B5%E1%84%87%E1%85%A9%E1%86%AB.png?alt=media&amp;token=53e1f9c4-79fa-474e-9e0d-568e7518ee01" alt="" width="563"><figcaption></figcaption></figure>

| colorTheme 값 | 설명          |
| ------------ | ----------- |
| green        | 녹색 테마 (기본값) |
| white        | 흰색 테마       |

### SDK v2 > 템플릿형 > 구성요소 선택

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

<table><thead><tr><th>구성요소</th><th>components 옵션</th><th width="98.86328125">필수 여부</th><th>비고</th></tr></thead><tbody><tr><td>네이버페이 구매 버튼</td><td>-</td><td>필수</td><td>유일한 필수 구성요소</td></tr><tr><td>네이버쇼핑 찜하기 버튼</td><td>wishlist</td><td>선택</td><td>-</td></tr><tr><td>네이버 톡톡 버튼</td><td>talkTalk</td><td>선택</td><td>톡톡 연동 시에만 노출</td></tr><tr><td>이벤트/혜택 메시지</td><td>benefitMessage</td><td>선택</td><td>내용은 네이버페이 관리자가 관리</td></tr><tr><td>혜택 코치마크</td><td>benefitCoachMark</td><td>선택</td><td>내용은 네이버페이 관리자가 관리</td></tr></tbody></table>

#### 템플릿형 버튼 예제

```
<script>
  async function registerOrder() {
    const response = await fetch('/api/naver-pay/register-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ /* 주문 정보 */ }),
    });
    return response.json();
  }

  Npay.order.create({
    buttonKey: 'YOUR_BUTTON_KEY',
    containerId: 'npay-button-container',
    orderRegistrationVersion: '2.1',
    type: 'template',
    colorTheme: 'green',
    enable: true,
    components: {
      talkTalk: true,
      wishlist: true,
      benefitMessage: true,
      benefitCoachMark: true,
    },
    onBuyClick: async function () {
      const orderResult = await registerOrder();
      return {
        key: orderResult.buyKey,
        merchantNo: 'YOUR_MERCHANT_NO',
      };
    },
    onWishlistClick: async function () {
      return {
        merchantId: 'YOUR_MERCHANT_ID',
        payProductId: 'YOUR_PRODUCT_ID',
      };
    },
  })
  .catch(function (error) {
    console.error('네이버페이 버튼 초기화 실패:', error);
  });
</script>
```

### SDK v2 > 커스텀형 > 스킨 코드

* 커스텀형을 선택하신 경우, 스킨 코드에서 직접 수정하셔야 합니다.
* 네이버페이 디자인 가이드를 참고해서 수정해야 합니다.
* 네이버페이 네이밍 규칙으로 'Npay'만 허용됩니다. (N pay, n-pay, NPay 등 사용 불가합니다.)
* 커스텀형 버튼에서는 혜택 메시지(`benefitMessage`)와 혜택 코치마크(`benefitCoachMark`)가 지원되지 않습니다.
* 네이버페이 로고 이미지는 [디자인 가이드](https://developers.pay.naver.com/design/brand/logo)에서 다운로드할 수 있습니다.
* 톡톡 연동은 판매자님께서 네이버페이 센터 또는 톡톡 파트너센터를 통해 직접 설정해 주셔야 합니다.
* 톡톡 연동 설정과 상관없이 톡톡 버튼은 항상 노출됩니다. 버튼을 숨기고 싶으신 경우, 스킨 코드를 직접 수정하셔야 합니다.

#### 버튼 식별 속성 <a href="#undefined" id="undefined"></a>

`data-npay-component` 속성을 사용하여 버튼과 SDK 기능을 연결합니다.

| data-npay-component 값 | 버튼 유형 | 연결 핸들러          |
| --------------------- | ----- | --------------- |
| buy                   | 구매하기  | onBuyClick      |
| wishlist              | 찜하기   | onWishlistClick |
| talktalk              | 톡톡    | SDK 내부 처리       |

#### 커스텀형 버튼 예제

```
<script>
  async function registerOrder() {
    const response = await fetch('/api/naver-pay/register-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ /* 주문 정보 */ }),
    });
    return response.json();
  }

  Npay.order.create({
    buttonKey: 'YOUR_BUTTON_KEY',
    containerId: 'custom-button-container',
    orderRegistrationVersion: '2.1',
    type: 'custom',
    onBuyClick: async function () {
      const orderResult = await registerOrder();
      return {
        key: orderResult.buyKey,
        merchantNo: 'YOUR_MERCHANT_NO',
      };
    },
    onWishlistClick: async function () {
      return {
        merchantId: 'YOUR_MERCHANT_ID',
        payProductId: 'YOUR_PRODUCT_ID',
      };
    },
  })
  .catch(function (error) {
    console.error('네이버페이 버튼 초기화 실패:', error);
  });
</script>
```
