# 결제 모듈 스크립트 가이드

## 결제 모듈 스크립트(ncp\_pay.js) 에 대하여

### 목적

샵바이에서 kcp, inicis, (구)LG-uPlus, naverpay(결제형/주문형), payco, kakaopay 등 다양한 pg를 이용한 결제를 할 때 프런트에서 간단한 코드 호출만으로 결제를 붙일 수 있도록 통일된 인터페이스를 만들어 주기 위해 제공하는 자바스크립트입니다.

### 사용법

* 결제 모듈 스크립트 import

```
<script src="https://shop-api.e-ncp.com/payments/ncp_pay.js"></script>
```

* `setConfiguration`을 통해 공통 설정을 사전에 지정해두면, 이후 `reservation` 호출 시 모든 PG사에서 동일한 동작을 보장합니다.

```
1.결제 모듈 기본 설정 적용 (NCPPay.setConfiguration)
 1-1. Oauth2 인증 방식을 사용하는 경우
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'shopbyAuthorization': accessToken ? `Bearer ${accessToken}` : '', // oauth2 토큰을 발급 받아 로그인한 사람의 토큰 값
      'accessToken': ''
  });

  1-2. AccessToken 인증 방식을 사용하는 경우
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'accessToken': accessToken ? ${accessToken} : ''  // accessToken 토큰을 발급 받아 로그인한 사람의 토큰 값 
  });

2.주문하기
  NCPPay.reservation(
    orderInfo,                     // 주문 정보 데이터 
    (result) => {                  // 주문 예약하기 api 성공시 콜백함수
      console.log('주문 성공');
    },
    (result) => {                  // 주문 예약하기 api 에러 발생시 콜백함수
      console.log('주문 실패');
    },
    false,                         // 주문 예약하기 api 에러 발생시 기본 얼럿 노출 여부 (true/false)
    {}                             // pg에 전달할 추가 파라미터
  );
```

#### reservation 에 필요한 data

* 아래 문서에 전달되어야 하는 reqeust 값을 json 형태로 data 파라메터로 전달합니다.
* [결제 예약 데이터 양식](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)

#### 결제 결과

* 성공인 경우 NCPPay.setConfiguration 에 설정한 confirmUrl 로 성공, 실패인 경우 결과를 리턴합니다.
* 성공인 경우
  * request parameter 로 결과 값을 SUCCESS 로 전달합니다.
  * 주문이 성공한 주문번호를 같이 전달해 줍니다.
  * ex)result=SUCCESS\&orderNo=123
* 실패힌 경우
  * request parameter 로 결과 값을 FAIL로 전달합니다.
  * message 에 실패한 이유를 같이 전달해 줍니다.
  * ex)result=FAIL\&message=잔액부족

#### 글로벌 쇼핑몰

* 글로벌 쇼핑몰의 경우, 결제 모듈 기본 설정 시 **언어(language)** 및 **통화 코드(currency code)** 정보를 함께 전달받습니다.

  이를 통해 각 국가별 결제 환경에 맞는 결제수단 및 표시 정보를 세팅할 수 있습니다.

```
1.결제 모듈 기본 설정 적용 (NCPPay.setConfiguration)
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'shopbyAuthorization': accessToken ? `Bearer ${accessToken}` : '', // oauth2 토큰을 발급 받아 로그인한 사람의 토큰 값
      'accessToken': '',
      'language': 'ko', // 언어
      'currency': 'KRW' // 통화 코드
  });
```

### 제약조건

* 추가로 각 PG 사에서 제공하는 결제 모듈 javascript 를 로드해야 합니다.

  기본 스킨에서는 주문서 화면에서 실행환경에 따라 아래와 같은 결제 모듈 javascript 를 로드하고 있습니다.

```
// 모바일 환경 체크는 프로젝트에 맞는 방식으로 추가 부탁드립니다.
const ksnetScriptUrl = isMobile ? 'https://kspay.ksnet.to/KSPayMobileV1.4/mall/js/kspay_api_ssl.js' : 'https://kspay.ksnet.to/KSPayWebV1.4/mall/js/kspay_api_ssl.js';

const payScripts = {
  [
    'https://shop-api.e-ncp.com/payments/ncp_pay.js',              // 결제모듈 스크립트 (필수)
    'https://nsp.pay.naver.com/sdk/js/naverpay.min.js',            // 네이버페이 
    'https://spay.kcp.co.kr/plugin/kcp_spay_hub.js',               // kcp
    'https://xpay.tosspayments.com/xpay/js/xpay_crossplatform.js', // 토스페이먼츠
    'https://pay.smartropay.co.kr/asset/js/SmartroPAY-1.0.min.js', // 스마트로
    'https://chai.finance/js/v1/payment.min.js',                   // 차이페이
    'https://web.nicepay.co.kr/v3/webstd/js/nicepay-3.0.js',       // 나이스페이
    'https://api.eximbay.com/v1/javascriptSDK.js',                 // 엑심베이
    'https://pay.billgate.net/paygate/plugin/gx_web_client.js',    // 갤럭시아머니트리
    ksnetScriptUrl                                                 // KSNET 
  ],
};
```

### payType 과 pgType 에 대하여

* 해당 쇼핑몰에서 사용설정한 PG와 결제 수단과 상품에 따라 해당 주문에서 사용 가능한 결제 수단을 [주문서 조회하기 api](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet) 에서 내려줍니다.
* 사용가능한 결제 수단에 따라 pgType 이 결정됩니다.

#### 제공 중인 payType과 pgType

* **payType**: 사용 가능한 결제수단
* **pgType**: 실제 결제를 발생시키는 외부 PG

| PayType 코드                          | 결제 수단                | PgType 코드            | 결제사         |
| ----------------------------------- | -------------------- | -------------------- | ----------- |
| CREDIT\_CARD                        | 신용카드                 | PAYCO                | PAYCO       |
| ACCOUNT                             | 무통장입금                | PAYPAL               | Paypal      |
| MOBILE                              | 휴대폰결제                | STRIPE               | 스트라이프       |
| REALTIME\_ACCOUNT\_TRANSFER         | 실시간계좌이체              | KCP                  | kcp         |
| VIRTUAL\_ACCOUNT                    | 가상계좌                 | INICIS               | 이니시스        |
| GIFT                                | 상품권                  | NONE                 | 무통장입금       |
| ATM                                 | ATM                  | KCP\_MOBILE          | kcp(모바일)    |
| PAYCO                               | PAYCO                | KCP\_APP             | kcp(앱)      |
| ZERO\_PAY                           | 0원결제                 | NAVER\_PAY           | 네이버페이       |
| ACCUMULATION                        | 적립금 전액 사용            | LIIVMATE             | 리브메이트       |
| PHONE\_BILL                         | 전화결제                 | PAYPALPRO            | Paypal pro  |
| POINT                               | 포인트결제                | ATHOR\_NET           | AthorizeNet |
| YPAY                                | 옐로페이                 | KAKAO\_PAY           | 카카오페이       |
| KPAY                                | 케이페이                 | NAVER\_EASY\_PAY     | 네이버페이(결제형)  |
| PAYPIN                              | 페이핀                  | LG\_U\_PLUS          | 토스페이먼츠      |
| INIPAY                              | INIPay 간편결제          | TOSS\_PAYMENTS       | 토스페이먼츠      |
| PAYPAL                              | PayPal               | CHAI                 | 차이          |
| STRIPE                              | 스트라이프                | SMARTRO\_PAY         | 스마트로        |
| NAVER\_PAY                          | 네이버페이 주문형            | NICEPAY              | 나이스페이       |
| KAKAO\_PAY                          | 카카오페이                | MY\_PAY              | 마이페이        |
| NAVER\_EASY\_PAY                    | 네이버페이 결제형            | EXIMBAY\_GLOBAL      | 엑심베이(글로벌)   |
| NAVERPAY\_SIMPLE                    | 네이버페이                | EASY\_PAY            | 이지페이        |
| SAMSUNG\_PAY                        | 삼성페이                 | GALAXIA\_MONEY\_TREE | 갤럭시아머니트리    |
| CHAI                                | 차이                   | KSNET                | KSNET       |
| TOSS\_PAY                           | 토스페이                 | EASY\_PAY\_OVERSEAS  | 이지페이(해외 전용) |
| SK\_PAY                             | SK페이                 | BLUE\_WALNUT         | 블루월넛        |
| APPLE\_PAY                          | 애플페이                 | HMG\_PAY\_H          | 현대페이        |
| LPAY                                | 엘페이                  | HMG\_PAY\_K          | 기아페이        |
| ESCROW\_REALTIME\_ACCOUNT\_TRANSFER | 실시간계좌이체-에스크로         | APP\_CARD            | 앱카드         |
| ESCROW\_VIRTUAL\_ACCOUNT            | 가상계좌-에스크로            | TOSS\_EASY\_PAY      | 토스 간편결제     |
| VERITRANS\_CARD                     | Veritrans CreditCard | VERITRANS            | Veritrans   |
| TOASTCAM                            | 토스트캠                 | <p><br></p>          | <p><br></p> |
| UNION\_PAY                          | UnionPay             | <p><br></p>          | <p><br></p> |
| ALIPAY                              | Alipay Plus          | <p><br></p>          | <p><br></p> |
| WECHAT\_PAY                         | WeChat Pay           | <p><br></p>          | <p><br></p> |
| EXTERNAL\_PAY                       | 외부 결제 전액 사용          | <p><br></p>          | <p><br></p> |
| RENTAL                              | 렌탈결제                 | <p><br></p>          | <p><br></p> |
| PINPAY                              | 핀페이                  | <p><br></p>          | <p><br></p> |
| HMG\_PAY                            | HMG pay              | <p><br></p>          | <p><br></p> |
| APP\_CARD                           | 앱카드                  | <p><br></p>          | <p><br></p> |
| PAY\_PAY                            | 페이페이                 | <p><br></p>          | <p><br></p> |
| E\_CONTEXT                          | 일본 편의점결제             | <p><br></p>          | <p><br></p> |
| HAPPY\_VOUCHER                      | 국민행복바우처              | <p><br></p>          | <p><br></p> |
| ETC                                 | 기타결제수단               | <p><br></p>          | <p><br></p> |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workspace-help.nhn-commerce.com/contents/recommended/ncp_pay.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.