> 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/global/use_process/step_04/reserve.md).

# 주문 예약하기

주문 예약 시 필요한 언어, 통화, 배송지 정보를 설정하고 실제 결제 API 호출하는 화면입니다.

* 🅐 결제언어
* 🅑 결제통화
* 🅒 배송지
* 🅓 결제하기 버튼

> [POST /payments/reserve](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)

```
▶︎ 주문 예약하기 API
주문을 예약하는 API 입니다.
```

***

## 🅐 결제언어 <a href="#id-3cspan-style-22color-rgb-34-34-34-22-3e-f0-9f-85-90-3c-span-3e-ea-b2-b0-ec-a0-9c-ec-96-b8-ec-96-b4" id="id-3cspan-style-22color-rgb-34-34-34-22-3e-f0-9f-85-90-3c-span-3e-ea-b2-b0-ec-a0-9c-ec-96-b8-ec-96-b4"></a>

language 헤더를 이용하여 결제창의 언어를 선택할 수 있습니다.

## 🅑 결제통화

currency 헤더를 이용하여 결제 시의 언어/통화 수단을 선택할 수 있습니다.\
입력되는 모든 결제 금액은 원화(KRW) 기준이며, currency 입력 값에 따라 몰에 설정된 환율로 자동 계산되어 엑심베이 PG에 요청됩니다.

## 🅒 `배송지`

해외 배송지의 아래 값을 입력해야 합니다.

* `receiverZipCd` : zipCode
* `receiverAddress` : 주소 (도시, 주 정보는 제외)
* `receiverDetailAddress` : 상세 주소
* `receiverCity` : 도시
* `receiverState` : 주
* `receiverFirstName` : 이름
* `receiverLastName` : 성
* `countryCd` : 국가
* `orderAdditionalInfo` : 추가 정보 (대만인 경우 여권번호)

`countryCd`, `receiverState` 기준으로 지역별 배송비가 계산됩니다.

설정한 배송지 정보에 따라 결제 시도 시, 하기 케이스에 대해 400에러가 발생됩니다.\
\- 설정한 `countryCd`(국가)에 최대 주문금액이 설정되어 있고 해당 주문 금액을 초과한 경우\
\- 설정한 `countryCd`(국가)가 배송불가 국가로 설정된 경우

## 🅓 `결제하기 버튼`

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

<figure><img src="/files/DjpHzCLEOkSeTP4o1B1E" alt="" width="196"><figcaption></figcaption></figure>

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

결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 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(언어)`를 추가로 입력하여야 합니다.\ <mark style="color:orange;">현재 통화는 KRW(원화) USD(미국 달러), JPY(엔화), CNY(위안화)를 지원하며, 언어는 KO(한국어), EN(영어), JA(일본어), ZH(중국어)를 지원합니다.</mark>

```
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 데이터 양식을 참고하시길 바랍니다.\
[주문 예약하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve) 를 사용하면 결제가 진행됩니다.

Request Body 내 `payType`결제수단과 `PgTypes`외부 PG사에 대해 안내드립니다.\
해당 값들은 `GET /order-sheets/{orderSheetNo}` 주문서 조회하기 API에서, 해당 쇼핑몰/상품이 설정한 결제수단에 따라 `availablePayTypes` 사용가능한 결제정보를 응답 값으로 내려줍니다.\
쇼핑몰에서 다양한 PG사와 계약해서 결제수단을 제공할 수 있기 때문에, `payType`을 기준으로 `pgTypes`를 내려주고 있으니 프론트에서 구현 시 내려온 `pgTypes`에 따라 결제모듈을 제공할 수 있습니다.

<mark style="color:orange;">PayPal의 경우 해외 배송지 정보를 필수로 요청해야 합니다.</mark>\ <mark style="color:orange;">또한 2017.02.20 기준으로 지정된 10개 국가(Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA)에 대해서는</mark> `shippingAddress.receiverState` <mark style="color:orange;">값이 필수이며, State Code 값은 아래 URL을 통하여 확인해 주시기 바랍니다.</mark>\
<https://developer.paypal.com/docs/api/reference/state-codes/>

`ShippingAdrdress.countryCd` <mark style="color:orange;">값은 ISO-3166 두 자리 국가코드로 요청하셔야 합니다.</mark>

```
{
  "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로 성공 또는 실패 결과를 리턴합니다.\
이후 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.

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

* 성공 시

  * request parameter 로 결과 값을 `SUCCESS` 로 전달합니다.
  * 주문이 성공한 주문 번호를 함께 전달합니다.

  ex)result=SUCCESS\&orderNo=123
* 실패 시

  * request parameter 로 결과 값을 `FAIL`로 전달합니다.
  * message에 실패 사유를 함께 전달합니다.

  ex) result=FAIL\&message=잔액부족