주문서
주문서 화면을 소개합니다.
Last updated
주문서 화면을 소개합니다.
Last updated
(intro) 주문서 화면 진입 로직
🅐 주문상품 정보
🅑 주문자 정보
🅒 배송지 정보
🅓 혜택 적용
🅔 결제수단 선택
🅕 결제 정보
🅖 약관 동의
🅗 결제 편의 모듈 javascript (결제하기 버튼)
앞서 소개한 문서인 상품 상세화면, 장바구니 화면 에서 POST /order-sheets 주문서 생성 요청 API를 통해 획득한 orderSheetNo(주문서 번호)에 해당하는 주문 상품 상세 정보를 통해 '주문서 화면'을 구현합니다.
단, 미로그인 상태인 경우 로그인 화면을 먼저 노출한 뒤,
로그인 실행 또는 [비회원 주문하기] 버튼을 통해 주문서 화면에 진입합니다.
주문서 화면에서는 회원과 비회원에 따른 화면에 대해 각각 설명합니다.
주문한 상품 목록과 기본 금액 정보를 노출하는 영역입니다. 앞서 소개드린 장바구니 화면과 동일한 화면 구성입니다.
POST /order-sheets를 통해 '주문서가 생성된 시점'에 확정된 금액만 노출됩니다.
단, 배송지 변경 / 쿠폰 / 적립금 사용에 따른 최종 결제금액은 🅔 결제정보 영역에 실시간으로 반영됩니다.
GET /order-sheets/{orderSheetNo}
► 주문서 가져오기 주문서 상세 정보를 조회합니다.
앞서 POST /order-sheets 주문서 생성 요청 API를 통해 획득한 orderSheetsNo(주문서 번호)에 해당하는 주문 상품 상세 정보를 호출합니다.
앞으로 본 주문서의 각 화면 영역을 구현하기 위해, 해당 API가 🅑 주문자 정보, 🅒 배송지 정보에서도 사용되며 각 항목에서 다시 소개해 드립니다.
주문 상품의 가격 정보는 deliveryGroups 내 각 옵션들이 포함한 금액 정보 (구매 금액, 할인 금액, 배송비)를 합산하여 화면에 노출합니다. 단, 비회원 주문인 경우 accessToken을 비워둡니다.(null)
주문자 정보를 노출 및 입력하는 영역으로 회원 / 비회원에 따라 다른 화면이 노출됩니다.
앞서 소개한 GET /order-sheets/{orderSheetsNo} 응답 값 중 orderContact 값을 통해 회원 정보를 자동으로 출력할 수 있으며, 해당 화면에서 주문자가 직접 수정 가능합니다.
회원이 보유하지 않은 정보는 공란으로 표시되며, 주문자가 직접 입력해야 합니다.
간편 로그인 회원의 경우 '회원명, 휴대폰 번호, 이메일' 정보가 orderContact에 없을 수 있습니다.
비회원 주문인 경우 ordererContact가 null 입니다. 따라서 주문자 정보 입력란이 모두 비어있으며, 주문자가 직접 입력할 수 있습니다.
비회원 주문 조회 시 사용할 '주문 비밀번호'를 입려할 수 있는 화면 영역이 추가되어야 합니다.
주문자의 배송지 정보를 노출 및 입력하는 화면 영역으로 회원 / 비회원에 따라 다른 화면이 노출됩니다.
단, 배송지 변경에 따른 배송비 금액 변동이 있을 수 있습니다.
실시간으로 변동되는 최종 결제 금액은 🅔 결제정보 영역을 참고해주시길 바랍니다.
앞서 소개한 GET /order-sheets/{orderSheetsNo}응답 값 중 orderSheetAddress 값을 통해 배송지 정보를 자동으로 출력할 수 있으며, 해당 화면에서 주문자가 직접 수정 가능합니다.
배송지 확인 항목은 주문자가 기본 배송지, 최근 배송지, 신규 배송지 중 선택할 수 있습니다.
기본 배송지 : mainAddress 값을 통해 디폴트로 자동 출력되는 항목입니다.
최근 배송지 : recentAddress 값을 통해 회원의 주문 내역 중 가장 마지막에 주문 완료된 배송지 정보를 출력합니다.
신규 배송지 : 공란이 출력되며 주문자 직접 입력이 가능한 항목입니다.
배송지 주소 입력 후 '회원정보 반영' 체크 박스 클릭 후 주문 완료 시, 해당 배송 정보의 주소가 회원의 주소 정보에 업데이트 되며, 업데이트 시 회원정보 수정 log에 반영됩니다.
이후 🅖 결제하기 영역에서 소개 드릴 POST /payments /reserve 결제하기 API에서 Request Body의 updateMember 을 true 로 보내면 회원정보의 주소가 입력된 배송지 정보로 업데이트 됩니다.
회원(member) 노출되는 기능입니다. 주문서 화면에서 [배송지 관리] 버튼 클릭 시 아래와 같이 '배송지 관리' 팝업이 출력되며, 해당 회원이 가지고 있는 모든 배송지 정보를 조회 및 선택/수정/추가/삭제 할 수 있습니다.
GET /profile/shipping-addresses
► 배송지 목록 가져오기 배송지 상세 정보를 조회합니다.
bookedAddresses는 '배송지 관리'에서 관리되는 배송지 목록을 내려주고 있습니다.
POST /profile/shipping-addresses
► 배송지 등록하기 배송지 정보를 추가합니다.
addressType 배송지 유형은 크게 2가지입니다.
book
저장된 배송지를 의미합니다.
개수 제한 없이 등록이 가능합니다.
'배송지 관리' 내 등록 추가된 주소
🅖 결제하기 영역에서 소개될 POST /payments/reserve 결제하기 API에서 Request Body의 saveAddressBook을 true로 보낼 경우 저장되는 주소
RECENT
최근 배송지를 의미합니다.
주문 완료 시 자동 저장됩니다.
해당 API에서는 최대 10개까지 최근 배송지를 내려줄 수 있으나, 기본 스킨에서는 최근 배송지를 1개만 사용하고 있습니다.
RECURRING_PAY
정기결제 배송주소로서, shop by premium에서 사용되는 항목입니다.
[배송지 추가] 버튼 클릭 시 노출되는 팝업과 동일하나, 공란이 아닌 선택한 배송지 정보가 등록된 상태로 노출됩니다.
PUT /profile/shipping-addresses/{addressNo}
► 배송지 수정하기 선택한 배송지 번호 기준으로 배송지의 상세 정보를 수정합니다.
DELETE /profile/shipping-addresses/{addressNo}
► 배송지 삭제하기 선택한 배송지 번호 기준으로 배송지의 정보를 삭제합니다.
비회원 주문인 경우, 앞서 소개한 GET /order-sheets/{orderSheetsNo}응답 값 중 orderSheetAddress값이 null이므로 주문자가 배송지 정보를 직접 입력해야합니다.
[우편번호 찾기] 버튼 클릭 시, 우편번호 찾기 레이어가 출력됩니다.
GET /adresses/search ► 주소 조회하기 검색된 키워드로 주소 정보를 조회합니다.
상품의 해외배송 여부에 '해외배송 상품' 체크 표시된 상품인 경우, '개인통관고유부호' 입력 항목이 추가로 노출됩니다. [개인통관고유부호 발급] 버튼 클릭 시, 관세청 개인통관고유부호 발급 사이트가 출력됩니다.
'개인통관고유부호'는 회원 / 비회원 동일하게 적용됩니다.
회원의 경우에만 '쿠폰 사용' 및 '적립금 사용' 항목이 노출되며, 비회원의 경우 노출되지 않습니다.
비회원 주문하기 시, 혜택 적용 영역에서 [회원 로그인] 클릭 시 로그인 화면으로 이동합니다.
회원(member)에게만 노출되는 기능입니다.
GET /order-sheets/{orderSheetNo}/coupons
► 적용 가능한 쿠폰정보 조회하기 해당 주문서에 적용 가능한 모든 쿠폰 (상품쿠폰, 주문쿠폰)을 조회합니다.
주문서 화면에서 [쿠폰 사용] 버튼 클릭 시, 해당 API를 통해 쿠폰 적용하기 팝업이 발생합니다. 회원이 이미 발급 받아 보유한 쿠폰 중, 해당 주문서에 적용 가능한 모든 쿠폰 (상품쿠폰, 주문쿠폰)을 노출합니다.
제공하는 쿠폰의 유형에는 '상품 쿠폰'과 '주문 쿠폰 (장바구니쿠폰)' 2가지 종류가 있습니다. 각각 개별 상품 혹은 주문 단위 (장바구니)로 적용이 가능합니다.
상품 쿠폰
상품 단위의 쿠폰으로, 하나의 상품에는 하나의 상품 쿠폰만 적용할 수 있습니다.
하나의 상품에 특정 쿠폰(couponNo기준)을 적용했을 경우, 다른 상품에는 해당 쿠폰을 적용할 수 없으며 '사용 불가' 안내 메시지가 출력됩니다.
만약 회원이 동일한 상품 쿠폰을 여러 장 발급 받았을 경우, 각 쿠폰은 couponNo기준으로 별개의 쿠폰이므로 하나의 상품에만 적용 가능합니다.
'쿠폰 미사용' 옵션이 가장 상단에 출력되며, 이후 할인 금액이 높은 순 > 등록일 기준 최신 순으로 정렬됩니다.
주문 쿠폰 (장바구니 쿠폰)
주문서에 적용할 수 있는 쿠폰으로, 주문서 당 하나의 주문 쿠폰만 적용이 가능합니다.
배송비를 제외한 주문금액에 적용되는 쿠폰입니다.
결제 수단을 선택할 수 있는 영역입니다.
단, 적립금 전액 결제 또는 결제정보에서 '최종 결제 금액'이 0원인 경우, 해당 영역이 노출되지 않습니다.
아래 어드민 경로에서 결제수단 사용 설정에 따라 노출 항목이 달라집니다.
GET /order-sheets/{orderSheetNo}
► 주문서 가져오기 주문서 상세 정보를 조회합니다.
응답 값 중 availablePayTypes의 payType를 통해 위와 같이 어드민에서 설정한 결제 수단 화면을 노출합니다. 비회원 주문인 경우 accessToken을 비워둡니다. (null) 이후 '🅗결제하기 버튼' 클릭 시, 선택된 각 결제 수단에 따라 해당 결제 모듈이 팝업 형태로 노출됩니다.
단, '무통장 입금'의 경우 별도의 결제 모듈을 사용하지 않으므로' 입금자명 / 계좌번호를 추가로 입력 받아 🅗 결제하기 API 호출 시 전달해야 합니다. 계좌 정보의 경우' 응답 값 중 tradeBankAccountInfos을 참고하실 수 있습니다.
🅐 주문상품 정보 영역에서 노출되었던 금액 정보에서, 🅓 혜택 적용 정보를 실시간으로 반영한 최종 결제금액 화면입니다.
최종 금액을 계산하는 로직은 GET /order-sheets/{orderSheetNo}/calculate 단일 API만 사용하시기 바랍니다.
POST /order-sheets/{orderSheetNo}/calculate
► 쿠폰 및 배송지 정보가 적용된 금액 조회하기 쿠폰 및 적립금 정보가 적용된 금액을 계산합니다.
🅓 혜택 적용 영역에서 쿠폰 사용 및 적립금 사용 금액이 변경될 때마다 해당 API를 호출하여, '최종 결제금액' 정보를 실시간으로 화면에 노출합니다.
비회원 주문인 경우 accessToken을 비워둡니다. (null)
accumulationUseAmt 적립금 정보
couponRequest 쿠폰 정보
🅖 약관 동의
결제하기 전 필요한 약관 동의에 대한 영역입니다. 회원 / 비회원에 따라 다른 화면이 노출됩니다.
기본 스킨에서는 기본적으로 '구매 진행 동의' 약관이 필수로 노출되며, 로그인 여부에 따라 그 외 약관이 추가로 노출됩니다.
아래 어드민 경로에서 약관 내용을 관리하실 수 있습니다.
► 몰 약관 조회하기 해당 쇼핑몰에 적용 중인 약관을 조회합니다.
해당 API는 주문서 구매 동의 화면 뿐 아니라, 회원가입, 회원탈퇴 및 쇼핑몰 푸터 영역에서도 활용됩니다.
[필수] 구매 진행 동의 약관
구매 진행동의 기본 문구가 노출됩니다. (구매하실 상품의 결제 정보를 확인하였으며, 구매 진행에 동의합니다.)
[필수] 개인정보 수집/이용 PI_COLLECTION_AND_USE_REQUIRED
[필수] 개인정보 판매자 제공 PI_SELLER_PROVISION (파트너사상품 포함 시)
[필수] 개인정보 국외이전 동의 TRANSFER_AGREE (해외배송상품 포함 시)
[필수] 통관정보 수집/이용 CLEARANCE_INFO_COLLECTION_AND_USE (해외배송상품 포함 시)
[필수] 주류구매 개인정보 제공 동의 PI_LIQUOR_PURCHASE_PROVISION (주류카테고리 상품 포함 시)
[필수] 구매 진행 동의 약관
구매 진행동의 기본 문구가 노출됩니다. (구매하실 상품의 결제 정보를 확인하였으며, 구매 진행에 동의합니다.)
[필수] 이용약관 USE
[필수] 개인정보 수집/이용 PI_COLLECTION_AND_USE_REQUIRED
[필수] 개인정보 판매자 제공 PI_SELLER_PROVISION (파트너사상품 포함 시)
[필수] 개인정보 국외이전 동의 TRANSFER_AGREE (해외배송상품 포함 시)
[필수] 통관정보 수집/이용 CLEARANCE_INFO_COLLECTION_AND_USE (해외배송상품 포함 시)
실제 결제 API 를 호출하는 화면입니다. '결제하기'버튼 클릭 시, 🅔결제 수단 선택에 따라 결제가 진행됩니다.
PG 결제수단 선택 시 각 PG사 결제 모듈이 레이어 팝업으로 출력됩니다.
무통장 입금 / 0원 결제 / 전액 적립금 결제인 경우, 버튼 클릭 시 주문 완료 처리됩니다.
결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 API를 호출합니다.
샵바이 서버에서는 Client에서 결제 API 를 호출할 수 있는 간단한 javascript 코드를 제공하고 있습니다. kcp, inicis, (구)LG-uPlus, naverpay(결제형/주문형), payco , kakaopay 등 다양한 pg를 이용한 결제 진행 시, 간단한 javascript 코드 호출만으로 통일된 인터페이스를 제공합니다.
다양한 결제 모듈에 따라 로직이 달라지지 않도록 개발되었으며, 결제 타입을 고려하지 않고 단일 타입으로 호출할 수 있습니다.
ncp_pay javascript 는 필수로 추가해야 하며, 쇼핑몰에 연결된 PG사에 따라 정해진 결제모듈 javascript 를 추가해야 합니다. 기본 스킨의 주문서 화면에는 아래의 결제모듈 javascript 가 추가되어 있습니다.
configuration 값 입력 후 reservation 값을 호출 시, 이후 코드는 어떤 결제 모듈이든 동일합니다.
단, 각 PG에서 제공하는 아래와 같은 예시코드를 javascript코드로 입력해야합니다.
reservation에 필요한 request 값은 아래 API 데이터 양식을 참고하시길 바랍니다.
► 결제하기 주문 된 결제를 진행합니다.
Request Body 내 payType 결제수단과 PgTypes외부 PG사에 대해 안내드립니다. 해당 값 들은 GET /order-sheets/{orderSheetNo} 주문서 조회하기 API에서, 해당 쇼핑몰/상품이 설정한 결제수단에 따라 availablePayTypes 사용가능한 결제정보 응답 값으로 내려줍니다.
쇼핑몰에서 다양한 PG사와 계약해서 결제수단을 제공할 수 있기 때문에, payType을 기준으로 pgTypes를 내려주고 있으니 프론트에서 구현 시 내려온 pgTypes에 따라 결제모듈을 제공할 수 있습니다.
NCPPay.setConfiguration에 설정한 confirmUrl로 성공 또는 실패 결과를 리턴합니다. 이후 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.
성공 시
request parameter 로 결과 값을 SUCCESS 로 전달합니다.
주문이 성공한 주문 번호를 함께 전달합니다.
ex)result=SUCCESS&orderNo=123
실패 시
request parameter 로 결과 값을 FAIL로 전달합니다.
message에 실패 사유를 함께 전달합니다.
ex)result=FAIL&message=잔액부족
