> For the complete documentation index, see [llms.txt](https://store-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://store-help.nhn-commerce.com/app/fin/eximbay.md).

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

## 이해하기

{% hint style="info" %}
결제 수단으로 엑심베이를 사용할 수 있는 방법을 참고하실 수 있는 가이드입니다
{% endhint %}

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

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

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

***

## 🅑 개발 환경 세팅 <a href="#undefined" id="undefined"></a>

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

* MID
* SecretKey
* 사용 결제 수단

개발 환경 세팅이 완료되면 [NHN 커머스 1:1문의](https://support.nhn-commerce.com/inquiry/contact) 답변을 통해 안내 드리겠습니다.

## 🅒 엑심베이 스킨 개발 <a href="#undefined" id="undefined"></a>

### 결제 수단 <a href="#ea-b2-b0-ec-a0-9c-ec-88-98-eb-8b-a8" id="ea-b2-b0-ec-a0-9c-ec-88-98-eb-8b-a8"></a>

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

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

> #### [GET /order-sheets/{orderSheetNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> ▶ 주문서 가져오기
>
> 주문서 상세 정보를 조회합니다.

`availablePayTypes` 의 `payType`은 `CREDIT_CARD`, `pgType`은 `EXIMBAY_GLOBAL` 로 보내주세요.\
비회원 주문인 경우 `shopbyAuthorization`은 빈 값('')으로 전달해 주세요.

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

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

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

{% hint style="warning" %}
화면 개발 형태 및 엑심베이와 계약한 결제 수단에 따라 화면은 상이할 수 있습니다.
{% endhint %}

<div align="left"><img src="https://nhnent.dooray.com/share/pages/ljUdQt8bSvqq0iED54TIzg/attach-files/3599336630710099887" alt="Inline-image-2023-08-03 17.34.27.497.png"></div>

<br>

### 결제 하기 버튼 <a href="#ea-b2-b0-ec-a0-9c-ed-95-98-ea-b8-b0-eb-b2-84-ed-8a-bc" id="ea-b2-b0-ec-a0-9c-ed-95-98-ea-b8-b0-eb-b2-84-ed-8a-bc"></a>

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

<div align="left"><img src="https://nhnent.dooray.com/share/pages/ljUdQt8bSvqq0iED54TIzg/attach-files/3599336630623392852" alt="Inline-image-2023-08-02 13.31.49.715.png"></div>

#### **ⓐ 결제 편의 모듈**

결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 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'
>     'shopbyAuthorization' : accessToken ? `Bearer ${accessToken}` : '', // Oauth2 인증 방식을 사용시 인증 헤더 구분 값
>     'accessToken': '', // Oauth 인증 방식을 사용시 인증 헤더 구분 값
>     '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](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/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에 실패 사유를 함께 전달합니다.