# 네이버페이(결제형)
{% hint style="warning" %}
**Deprecated**
이 문서는 더 이상 관리되지 않습니다.
[PortOne 개발자센터](https://developers.portone.io/)를 이용해주세요.
{% endhint %}
### 1. 네이버페이(결제형) PG 설정하기
[**네이버페이(결제형) 설정**](https://portone.gitbook.io/docs/ready/2.-pg/pg/undefined) 페이지의 내용을 참고하여 PG 설정을 진행합니다.
### 2.결제 요청하기
[JavaScript SDK](https://portone.gitbook.io/docs/sdk/javascript-sdk-old) IMP.**request\_pay**(param, callback)을 호출하여 네이버페이 결제형 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request\_pay(param, callback) 호출 후 **callback** 으로 수신 되며 모바일의 경우**m\_redirect\_url** 로 리디렉션됩니다.
{% tabs %}
{% tab title="일반결제창 요청" %}
{% code title="Javascript SDK" %}
```javascript
IMP.request_pay({
pg : 'naverpay.{파트너 ID}',
merchant_uid: "order_no_0001", //상점에서 관리하는 주문 번호
name : '주문명:결제테스트',
amount : 1004,
buyer_email : 'test@portone.io',
buyer_name : '구매자이름',
buyer_tel : '010-1234-5678',
buyer_addr : '서울특별시 강남구 삼성동',
buyer_postcode : '123-456',
naverUseCfm : '20221231', //이용완료일자(필요시 설정합니다)
naverPopupMode : true, //팝업모드 활성화
m_redirect_url : "{결제 완료 후 리디렉션 될 URL}",
naverPurchaserName: "구매자이름",
naverPurchaserBirthday: "20151201",
naverChainId: "sAMplEChAINid",
naverMerchantUserKey: "가맹점의 사용자 키",
naverProducts : [{
"categoryType": "BOOK",
"categoryId": "GENERAL",
"uid": "107922211",
"name": "한국사",
"payReferrer": "NAVER_BOOK",
"sellerId": "sellerA",
"count": 10
},
{
"categoryType": "MUSIC",
"categoryId": "CD",
"uid": "299911002",
"name": "러블리즈",
"payReferrer": "NAVER_BOOK",
"sellerId": "sellerB",
"count": 1
}]
}, function(rsp) { // callback 로직
//* ...중략... *//
});
```
{% endcode %}
**주요 파라미터 설명**
**`pg`** **string**
**PG사 구분코드**
**`naverpay`** 로 지정하면 됩니다.
**`merchant_uid`** **\*** **string**
**주문번호**
매번 고유하게 채번되어야 합니다.
**`amount`** **integer**
**결제금액**
**string** 이 아닌점에 유의하세요
**`naverUseCfm`** **`string`**
**`이용 완료일`** (yyyyMMdd 형식의 문자열로 **결제 당일 또는 미래의 일자**여야 함)
* 상품 유형에 따라 네이버페이-가맹점 간 필수값으로 계약되는 경우 입력합니다
**`name`** **\*** **`string`**
**`제품명`**
네이버페이 내부적으로 **`외 2개`** 의 표현이 자동생성되므로 **"`xxxx 외 2개"`** 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다.
**`naverPopupMode`** **`boolen`**
**`결제창 팝업여부`**
`false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다
**`m_redirect_url`** **`string`**
**`리다이렉트 URL`**
리디렉션 방식으로 진행(`naverPopupMode`: **false**)할 경우 결제 완료 후 리디렉션 될 URL
**`naverPurchaserName`** **`string`**
**`구매자 이름`**
결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 가맹점만 필수 입력**합니다.
**`naverPurchaserBirthday`** **`string`**
**`구매자 생년월일(yyyyMMdd)`**
결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 가맹점만 필수 입력**합니다.
\
\&#xNAN;**`naverProducts`** **\*** **`array`**
**`상품정보`**
네이버페이 매뉴얼의 **`productItems`** 파라미터와 동일합니다.
(해당 파라미터 누락시 네이버페이 검수를 통과할 수 없습니다.)
**`naverChainId`** **`string`**
**네이버페이 그룹형 가맹점용 chain id**
* 같은 파트너 ID로 두개 이상의 서비스를 운영하는 그룹형 가맹점의 경우에만 네이버페이로부터 전달받은 값을 필수 입력합니다.
* 비 대상 가맹점은 입력하지 않습니다.
**`naverMerchantUserKey`** **`string`**
**`가맹점의 사용자 키`** (개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다)
* 네이버페이 기준 **고위험군 제품을 판매하는 가맹점의 경우 필수** 입력합니다.
* 비 대상 가맹점은 입력하지 않습니다.
> \*\*`naverProducts`\*\*는 다음 6개의 속성으로 하나의 상품 정보를 표현하는 객체의 배열입니다.
>
> * **`categoryType`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고
> * **`categoryId`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고
> * **`uid`** (필수) : 가맹점 내부의 상품 고유 ID를 활용하는 것이 일반적이지만, 네이버페이 가이드 참고가 필요합니다. [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product)
> * **`name`** (필수) : 주문상품의 명칭
> * **`count`** (필수) : 상품 주문 개수
> * **`sellerId`** (선택) : 가맹점이 하위 판매자를 식별하기 위한 고유 ID(영문 대소문자 및 숫자 허용)
> * 가맹점의 업종이 통신판매중개업에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 대상 가맹점만 필수 입력합니다.
> * 비대상 가맹점은 입력하지 않습니다.
> * **`payReferrer`** (선택) : 네이버 플랫폼의 타 서비스와 제휴계약 후 유입분석을 진행하는 경우에만 입력 [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product_ref)
> {% endtab %}
{% tab title="정기결제창 요청" %}
**빌링키 발급받기**
{% code title="JavaScript SDK" %}
```javascript
IMP.request_pay({
pg : 'naverpay.{파트너 ID}',
customer_uid : 'gildong_0001_1234', //빌링, 필수 입력.
merchant_uid: "order_monthly_0001", //상점에서 생성한 고유 주문번호
name : 'Slim 요금제(1개월 단위)',
amount : 1004, //실 결제는 발생되지 않습니다.
buyer_email : 'test@portone.io',
buyer_name : '구매자이름',
buyer_tel : '010-1234-5678', //필수 입력.
buyer_addr : '서울특별시 강남구 삼성동',
buyer_postcode : '123-456',
naverProductCode : '반복결제 상품코드',
naverPopupMode : true, //팝업모드 활성화
m_redirect_url : "{등록 완료 후 리디렉션 될 URL}"
}, function(rsp) { // callback 로직
//* ...중략... *//
});
```
{% endcode %}
**주요 파라미터 설명**
**`pg`** **string**
**PG사 구분코드**
**`naverpay`** 로 지정하면 됩니다.
**`customer_uid`** **\*** **`string`**
**`빌링키`**
* 정기/반복 결제 등록을 위해서 지정해야 합니다. 미 지정 시, 일반결제로 진행됩니다.
* 등록 후 해당 키를 사용해 반복결제 승인을 요청할 수 있습니다.
**`merchant_uid`** **\*** **string**
**주문번호**
매번 고유하게 채번되어야 합니다.
**`amount`** **integer**
**결제금액**
**string** 이 아닌점에 유의하세요
**정기/반복 결제 등록과정에서는 ****결제승인이 이뤄지지 않습니다****.**
**`naverProductCode`** **\*** **`string`**
**`가맹점의 상품코드`**
* 동일한 고객이 동일상품에 대해 중복으로 반복결제 등록하는 것을 방지하기 위한 파라미터입니다.
* 기본값은 random으로 자동 생성되어 중복결제가 가능하므로 값을 지정해 주세요.
**`name`** **\*** **`string`**
**`제품명`**
네이버페이 내부적으로 **`외 2개`** 의 표현이 자동생성되므로 **"`xxxx 외 2개"`** 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다.
**`naverPopupMode`** **`boolen`**
**`결제창 팝업여부`**
`false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다
**`m_redirect_url`** **`string`**
**`리다이렉트 URL`**
리디렉션 방식으로 진행(`naverPopupMode`: **false**)할 경우 결제 완료 후 리디렉션 될 URL
**결제요청하기**
빌링키 발급이 완료되면 설정한 **`customer_uid`** 를 이용하여 결제승인 API를 호출하여 결제를 요청하거나 결제를 예약할 수 있습니다
**결제 요청방법**
REST API [**/subscribe/payments/again**](https://portone.gitbook.io/docs/api/api-4/api) 를 호출하여 결제를 요청할 수 있습니다.
* `customer_uid` : 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid`
* `merchant_uid` : 가맹점 주문번호
* `amount` : 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함)
* `tax_free` : `amount` 중 면세공급가액 (기본값: 0)
* `name` : 주문의 명칭
* `extra.naverUseCfm` : 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-가맹점 간 필수값으로 계약되는 경우 입력합니다.
{% code title="sample json" %}
```json
{
"customer_uid" : "gildong_0001_1234",
"merchant_uid" : "order_monthly_0002", //재사용 불가
"amount" : 10000,
"name" : "Slim 요금제(최초과금)",
"extra" : {
"naverUseCfm" : "20201001"
}
}
```
{% endcode %}
{% code title="form-urlencoded" %}
```
customer_uid={가맹점의 결제 고객을 특정하는 Unique Key}&merchant_uid={가맹점 주문번호}&amount=10000&name=Slim 요금제(최초과금)&extra[naverUseCfm]=20201001
```
{% endcode %}
**결제 예약방법**
REST API[ **/subscribe/payments/schedule**](https://portone.gitbook.io/docs/api/api-3/api)를 호출하여 결제예약을 할 수 있습니다.
* `customer_uid` : 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid`
* `schedules` : 결제 예약 정보 객체 배열(1개 이상 설정 가능)
* `merchant_uid` : 가맹점 주문번호
* `schedule_at` : 결제요청 예약시각 (UNIX timestamp)
* `amount` : 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함)
* `extra.naverUseCfm` : 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-가맹점 간 필수값으로 계약되는 경우 입력합니다.
{% code title="sample json" %}
```json
{
"customer_uid" : "gildong_0001_1234",
"schedules": [
{
"merchant_uid" : "order_monthly_0003", //재사용 불가
"schedule_at" : 1519862400,
"amount" : 10000,
"extra" : {
"naverUseCfm" : "20201001"
}
}
]
}
```
{% endcode %}
{% code title="form-urlencoded" %}
```
customer_uid={가맹점의 결제 고객을 특정하는 Unique Key}&schedules[0][merchant_uid]={가맹점 주문번호}&schedules[0][schedule_at]={결제요청 예약시각 UNIX timestamp}&schedules[0][amount]=10000&schedules[0][extra][naverUseCfm]=20201001\
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**연동 주의사항**
**에러 메시지 비 가공**
결제창 호출(IMP.request\_pay 함수)후 결제창 하단의 “취소" 버튼 클릭 등으로 결제 프로세스가 중단되거나 잔액 부족, 한도 초과, 100원 미만 결제 등의 사유로 결제에 실패하면 콜백 함수(popup 방식)/m\_redirect\_url(리디렉션 방식)로 전달되는 결제 결과(response 객체/쿼리 파라미터)에 실패 사유(error\_msg)가 전달됩니다. 이 에러 메시지는 사용자에게 가공 없이 그대로 노출되어야 합니다. 해당 규칙 미 준수시 네이버페이 실 검수 진행시 수정요청 받게 됩니다.
예) error\_msg가 “잔액 부족"이라고 가정할때, "결제에 실패하였습니다. 실패 사유:" + "잔액 부족"과 같은 형태로 가공되면 안됨
**100원 미만 결제 처리**
네이버페이 - 결제형의 최소 결제 금액은 100원이기 때문에, 100원 미만 결제 요청에 대해 예외 처리가 되어있어야 합니다.
예) 사용자에게 최소 결제 금액이 100원이라 결제를 할 수 없다는 의미를 담는 에러 메시지가 노출되어야 함
**환불 API 요청 시 추가 속성**
아임포트 환불 API인 `POST /payments/cancel` 호출 시 다음 추가 속성를 설정해야 합니다.
* `extra.requester` : API를 호출하는 출처. 다음 중 선택 :
* customer : 구매자에 의한 요청
* admin(기본값) : 어드민에 의한 요청
* `reason`: 결제 취소 사유.
**예시(json)**
```
{
"imp_uid" : "imp_123412341234", //환불처리할 아임포트 거래번호
"amount" : 3000, //환불할 금액
"reason": "결제 취소 사유", //실제 사유와 같아야 함
"extra" : {
"requester" : "customer"
}
}
```
**예시(form-urlencoded)**
```
imp_uid=imp_123412341234&amount=3000&extra[requester]=customer
```
{% endhint %}
{% hint style="info" %}
**"API 호출 권한이 없습니다"**
네이버페이 결제형 연동은 **네이버페이 검수진행이 시작되기 전까지는 운영환경에서 결제창 호출시**
**위와 같은 오류가 도출**됩니다. 해당 부분은 검수가 진행되면 해결되는 부분이기 때문에 무시해주시면 됩니다.
{% endhint %}
거래 취소 시 유의사항
포트원 환불 API인 `POST` [**`/payments/cancel`**](https://portone.gitbook.io/docs/api/api-1/api) 호출시 아래 파라미터를 반드시 설정해 주셔야 합니다. (**해당 파라미터 누락시 네이버페이 실 검수를 통과할 수 없습니다.**)
* **`extra.requester`** : API를 호출하는 출처
* **`customer`** : 구매자에 의한 요청
* **`admin`**(기본값) : 어드민에 의한 요청
* **`reason`**: 결제 취소 사유.
**예시(json)**
```javascript
{
"imp_uid" : "imp_123412341234", //환불처리할 포트원 거래번호
"amount" : 3000, //환불할 금액
"reason": "결제 취소 사유", //실제 사유와 같아야 함
"extra" : {
"requester" : "customer"
}
}
```
**예시(form-urlencoded)**
```
imp_uid=imp_123412341234&amount=3000&extra[requester]=customer
```