주문 예약하기

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

• 🅐 결제언어

• 🅑 결제통화

• 🅒 배송지

• 🅓 결제하기 버튼

POST /payments/reserve

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

---

🅐 결제언어

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

🅑 결제통화

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

🅒 배송지

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

• receiverZipCd : zipCode

• receiverAddress : 주소 (도시, 주 정보는 제외)

• receiverDetailAddress : 상세 주소

• receiverCity : 도시

• receiverState : 주

• receiverFirstName : 이름

• receiverLastName : 성

• countryCd : 국가

• orderAdditionalInfo : 추가 정보 (대만인 경우 여권번호)

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

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

🅓 결제하기 버튼

실제 결제 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'
    '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 를 사용하면 결제가 진행됩니다.

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/docs/api/reference/state-codes/

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

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

• 성공 시

  • request parameter 로 결과 값을 SUCCESS 로 전달합니다.

  • 주문이 성공한 주문 번호를 함께 전달합니다.

  ex)result=SUCCESS&orderNo=123

• 실패 시

  • request parameter 로 결과 값을 FAIL로 전달합니다.

  • message에 실패 사유를 함께 전달합니다.

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