> 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/ncp_pay.md).
# 결제 모듈 스크립트 가이드
## 결제 모듈 스크립트(ncp\_pay.js) 에 대하여
### 목적
샵바이에서 kcp, inicis, (구)LG-uPlus, naverpay(결제형/주문형), payco, kakaopay 등 다양한 pg를 이용한 결제를 할 때 프런트에서 간단한 코드 호출만으로 결제를 붙일 수 있도록 통일된 인터페이스를 만들어 주기 위해 제공하는 자바스크립트입니다.
### 사용법
* 결제 모듈 스크립트 import
```
```
* `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('주문 실패'); // 아래 4번째 인자 값과 무관하게 항상 호출됨
},
false, // 주문 예약하기 api 에러 발생시, 기본 얼럿 노출 비활성화 여부(true: 안 띄움 / false: 띄움)
// - 기본값 false
// - false: 얼럿 띄움
// - true : 얼럿을 띄우지 않음. 에러 UI를 직접 제어할 때 사용
// (true로 두면 사용자에게 보일 에러 UI는 3번째 인자(failCallback)에서 직접 처리)
{} // 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 | 토스트캠 |
|
|
| UNION\_PAY | UnionPay |
|
|
| ALIPAY | Alipay Plus |
|
|
| WECHAT\_PAY | WeChat Pay |
|
|
| EXTERNAL\_PAY | 외부 결제 전액 사용 |
|
|
| RENTAL | 렌탈결제 |
|
|
| PINPAY | 핀페이 |
|
|
| HMG\_PAY | HMG pay |
|
|
| APP\_CARD | 앱카드 |
|
|
| PAY\_PAY | 페이페이 |
|
|
| E\_CONTEXT | 일본 편의점결제 |
|
|
| HAPPY\_VOUCHER | 국민행복바우처 |
|
|
| ETC | 기타결제수단 |
|
|