엑심베이 결제 수단 추가 가이드

이해하기

결제 수단으로 엑심베이를 사용할 수 있는 방법을 참고하실 수 있는 가이드입니다

엑심베이 도입 프로세스를 소개합니다.

🅐 엑심베이 PG 계약
🅑 개발 환경 세팅
🅒 엑심베이 스킨 개발

본 문서에서는 🅑 개발 환경 세팅과 🅒 엑심베이 스킨 개발에 대해 안내하고 있으며, 🅐 엑심베이 PG 계약이 선행으로 진행되어 있어야 🅑 개발 환경 세팅과 🅒 엑심베이 스킨 개발이 가능합니다.

🅑 개발 환경 세팅

결제창 테스트를 진행하기 위해서는 개발 환경 세팅이 필요합니다. 개발 환경 세팅을 위해 엑심베이와 계약 완료 후, 아래 정보를 NHN 커머스 1:1문의를 통해 전달부탁드리겠습니다.

MID
SecretKey
사용 결제 수단

개발 환경 세팅이 완료되면 NHN 커머스 1:1문의 답변을 통해 안내 드리겠습니다.

🅒 엑심베이 스킨 개발

결제 수단

엑심베이 결제 수단을 주문서 페이지 내에 노출할 수 있습니다.

단, 적립금 전액 결제 또는 최종 결제 금액이 0원일 경우 해당 영역은 노출되지 않으며, 엑심베이와 계약한 결제 수단만 노출할 수 있습니다. 현재 결제 수단은 신용카드만 사용할 수 있습니다.

GET /order-sheets/{orderSheetNo}
▶ 주문서 가져오기
주문서 상세 정보를 조회합니다.

availablePayTypes 의 payType은 CREDIT_CARD, pgType은 EXIMBAY_GLOBAL 로 보내주세요. 비회원 주문인 경우 accessToken은 비워주세요.(null)

엑심베이 결제를 사용하기 위해서는 엑심베이 SDK 라이브러리가 필요하기 때문에 하기 스크립트를 주문서 페이지에 추가해주세요.

<script type="text/javascript" src="https://api.eximbay.com/v1/javascriptSDK.js"></script>

스킨의 결제 수단 선택 화면을 아래와 같이 구현할 수 있습니다.

화면 개발 형태 및 엑심베이와 계약한 결제 수단에 따라 화면은 상이할 수 있습니다.

결제 하기 버튼

실제 결제 API를 호출하는 화면입니다. '결제 하기'버튼 클릭 시, 아래와 같은 엑심베이 결제 모듈이 레이어 팝업 형태로 출력됩니다.

ⓐ 결제 편의 모듈

결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 API를 호출합니다.

샵바이 서버에서는 Client에서 결제 API를 호출할 수 있는 간단한 javascript 코드를 제공하고 있습니다. 쇼핑몰에서 javascript를 로드해주세요.

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

ⓑ 결제 모듈 javascript

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

 const payScripts = {
      [
        'https://nsp.pay.naver.com/sdk/js/naverpay.min.js',
        'https://shop-api.e-ncp.com/payments/ncp_pay.js',
        'https://spay.kcp.co.kr/plugin/kcp_spay_hub.js',
        'https://xpayvvip.uplus.co.kr/xpay/js/xpay_crossplatform.js',
      ],
  };

Configuration 값 입력 후 revervation 값을 호출해주세요.

엑심베이를 결제 수단으로 사용할 경우 NCPPay.setConfiguration 메소드를 호출하실 때 파라미터에 currency(통화단위)와 language(언어)를 추가로 입력하여야 합니다.

현재 통화는 KRW(원화), USD(미국 달러), JPY(엔화), CNY(위안화)를 지원하며, 언어는 KO(한국어), EN(영어), JA(일본어), ZH(중국어)를 지원합니다.

NCPPay.setConfiguration({
    'clientId': ncp.clientId, // shopby에서 발급받은 clientId
    'confirmUrl': 'payment-confirm.html', // 결과를 리턴받을 url
    'platform': 'PC', // 'PC or MOBILE_WEB or AOS or IOS'
    'accessToken': $("#accessToken").val(), // 로그인한 사람의 accessToken
    'currency': 'KRW', // 'KRW' or 'USD' or 'JPY' or 'CNY'
    'language': 'KO' // 'KO' or 'EN' or 'JA' or 'ZH'
  });

NCPPay.reservation(data, function (response) {
    alert("결제완료 되었습니다.");
  });

참고로 clientId는 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값입니다. (프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)

ㄴ 샵바이프로: environment.json 내 clientId 값으로 확인 가능합니다. ㄴ 샵바이프리미엄: 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능합니다.

단, 엑심베이가 제공하는 아래 코드를 javascript코드로 입력해야합니다.

<script type="text/javascript" src="https://api.eximbay.com/v1/javascriptSDK.js"></script>

ⓒ 결제하기 API

reservation에 필요한 request 값은 아래 API 데이터 양식을 참고하시길 바랍니다.

POST /payments/reserve
엑심베이의 경우 상기 API를 사용하면 결제가 진행됩니다.

Request Body 내 payType결제수단과 PgTypes외부 PG사에 대해 안내드립니다.

해당 값들은 GET /order-sheets/{orderSheetNo} 주문서 조회하기 API에서, 해당 쇼핑몰/상품이 설정한 결제수단에 따라 availablePayTypes 사용가능한 결제정보를 응답 값으로 내려줍니다.

쇼핑몰에서 다양한 PG사와 계약해서 결제수단을 제공할 수 있기 때문에, payType을 기준으로 pgTypes를 내려주고 있으니 프론트에서 구현 시 내려온 pgTypes에 따라 결제모듈을 제공할 수 있습니다.

PayPal의 경우 해외 배송지 정보를 필수로 요청해야 합니다.

또한 2017.02.20 기준으로 지정된 10개 국가(Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA)에 대해서는 shippingAddress.receiverState 값이 필수이며, State Code 값은 아래 URL을 통하여 확인해 주시기 바랍니다. https://developer.paypal.com/api/rest/reference/state-codes/

ShippingAddress.countryCd 값은 ISO-3166 두 자리 국가코드로 요청하셔야 합니다.

{
  "orderSheetNo": "202007230001814989",
  "shippingAddress": {
    "receiverAddress": "132, My Street", // Address 1
    "receiverDetailAddress": "PO BOX 123", // Address 2
    "receiverFirstName": "John", // First Name
    "receiverLastName": "Smith", // Last name
    "countryCd": "US", // Country/Region
    "receiverCity": "Kingston", // City
    "receiverState": "NY", // State/Province
    "receiverZipCd": "12401", // Zip/Postal Code
    "receiverContact1": "010-7770-7777", // Contact 1
    "receiverContact2": "031-8038-0000", // Contact 2(nullable)

    "usesShippingInfoLaterInput": false,
    "shippingInfoLaterInputContact": null,
    "requestShippingDate": null,
  },

ⓓ 결제 결과

NCPPay.setConfiguration에 설정한 confirmUrl로 성공 또는 실패 결과를 리턴합니다. 이후 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.

엑심베이에서 결제 승인이 된 후, 샵바이에 재고가 없는 등의 문제가 발생할 경우 바로 취소 처리되며 실패 응답 값을 내려줍니다.

성공 시 ex)result=SUCCESS&orderNo=123
- request parameter 로 결과 값을 SUCCESS 로 전달합니다.
- 주문이 성공한 주문 번호를 함께 전달합니다.
실패 시 ex)result=FAIL&message=잔액부족
- request parameter 로 결과 값을 FAIL로 전달합니다.
- message에 실패 사유를 함께 전달합니다.

Previous결제/금융 Next디자인/콘텐츠

Last updated 6 months ago