결제 모듈 스크립트 가이드

결제 모듈 스크립트(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 파라메터로 전달합니다.

• 결제 예약 데이터 양식

결제 결과

• 성공인 경우 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 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',    // 갤럭시아머니트리
  ],
};

payType 과 pgType 에 대하여

• 해당 쇼핑몰에서 사용설정한 PG와 결제 수단과 상품에 따라 해당 주문에서 사용 가능한 결제 수단을 주문서 조회하기 api 에서 내려줍니다.

• 사용가능한 결제 수단에 따라 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	기타결제수단