> 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/recurring-payment-api.md).
# \[엔터프라이즈]정기결제(배송) API 화면가이드
{% code overflow="wrap" %}
```
샵바이 엔터프라이즈의 정기결제(배송) 기능을 사용하기 위해, shop API로 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.
```
{% endcode %}
#### 01. 간단소개
* 기능요약
* 쇼핑몰 내 등록된 상품을 서비스어드민에서 정기결제(배송)상품으로 지정하여, 고객이 신청한 주문은 정기결제(배송) 해지일까지 희망배송일 마다 자동생성하는 기능입니다.\
#### 02. API 소개 및 화면 가이드
아래 API들을 활용하여 정기결제(배송)기능을 활용한 화면을 구현할 수 있습니다.
들어가기 앞서, 정기배송(결제)사용 여부를 응답하는 API를 소개합니다.
■ [주문설정 값 가져오기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderConfiguration/get-order-configuration) 확인하기
```
GET /order-configs
주문 설정값을 조회하는 API 입니다.
```
해당 API는 로그인 여부와 상관없이, 몰에 어느 페이지든 초기 진입 시 설정 값을 캐시로 저장합니다.
응답 값 내 `useRecurringPayment 몰 정기배송(결제) 사용 여부` 값을 통해, 해당 몰이 정기결제를 사용하는 몰인지 판단할 수 있습니다.\
정기결제를 사용하는 몰이면서 동시에 정기결제에 해당하는 상품인 경우, 아래 안내 드릴 '상품 상세페이지 화면'에서 정기배송 장바구니를 위한 UI를 노출해야 합니다.
응답 값 내 `recurringPaymentFreeGiftIssueType 정기결제 사은품 지급 기준` 값을 통해, 해당 쇼핑몰의 정기결제 사은품 지급 기준을 판단할 수 있습니다.\
RECURRING\_PAYMENT\_NO -> 정기결제 신청 번호 기준으로 사은품 지급\
RECURRING\_PAYMENT\_GROUP\_NO -> 정기결제 그룹 번호 기준으로 사은품 지급
#### 1) 상품 상세페이지 화면
서비스 어드민 > 상품관리 > 정기결제(배송) 상품관리에서 정기결제(배송)상품으로 등록하였을 경우\
위와 같이 정기배송 상품금액 출력 및 정기결제 장바구니 담기 기능을 화면에 구현할 수 있습니다.
■ [상품 상세조회 API](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product) 확인하기
```
GET /products/{productNo}
해당 상품 번호에 대한 상세, 이미지, 옵션 정보를 조회하는 API입니다
```
`regularDelivery (정기 결제 정보)` 값이 null로 리턴 될 경우, 정기결제(배송)상품이 아니라는 것을 판단할 수 있습니다.
응답 값 내 `regularDelivery (정기 결제 정보)` 값을 통해 즉시할인이 적용된 금액을 조회할 수 있습니다. 이를 바탕으로 정기배송 상품금액을 화면에 출력합니다.
참고로, 정기결제(배송) 상품의 경우 원 상품에 설정된 즉시할인가는 적용되지 않으며,\
서비스어드민 > 정기결제(배송)상품 관리> 정기결제(배송)상품 등록> 상품할인 설정에서 적용한 즉시할인이 상품할인에 적용됩니다.
\
\
■ [정기결제 장바구니 담기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-cart) 확인하기
```
POST /recurring-payments/cart
로그인된 유저의 장바구니에 해당 상품 및 옵션, 수량을 입력하는 API입니다
```
* 정기결제 장바구니 버튼클릭 시, 상품금액이 500원인지 확인 후 장바구니 담기 완료 처리합니다.
* 옵션가를 포함한 정기결제 즉시할인 적용가가 500원 미만인 경우, 정기결제건으로 처리가 불가합니다. (장바구니 담기 불가)\
이 경우, "상품가격 또는 할인금액 등 상품정보가 변경되었습니다. 다시 확인하시고 구매해 주세요."와 같은 알럿메시지가 출력되어야 합니다.
* 옵션이 필수이나, 옵션을 선택하지 않은 경우 '옵션을 선택해주세요'와 같은 알럿을 출력할 수 있습니다.
\
#### 2) 장바구니 화면
■ [정기결제 장바구니 조회 API](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart) 확인하기
```
GET /recurring-payments/cart
로그인된 유저의 정기결제 장바구니 목록을 조회하는 API 입니다
```
예시 장바구니 화면 내에서 '정기배송' 탭을 구현할 때 호출하는 API입니다.\
응답 값 내 deliveryGroups > orderProducts > orderProductOptions > `adjustableDeliveryCycle` 를 통해 정기결제 상품의 '배송 주기'를 화면에 출력할 수 있습니다.\
배송주기는 서비스어드민>상품관리>정기결제(배송) 상품관리에 등록된 배송주기가 출력됩니다.
참고로 장바구니 화면 내 '일반배송' 탭을 구현할 때는 해당 `GET/cart` API를 호출하면 됩니다. (참고:[장바구니 화면 가이드 보러가기](https://workspace-help.nhn-commerce.com/aurora-skinguide/api-1/cart))\
응답 값 배열을 `GET /recurring-payments/cart` 와 `GET/cart`가 서로 동일하게 맞추기 위해 `GET/cart` 에서도 `recurringDeliveryCycles (정기결제 배송주기)`를 내려주고 있으나\
기본적으로 정기결제 장바구니 화면은 `GET /recurring-payments/cart` 으로 구현하실 수 있습니다.
※ 500원 미만의 상품이 장바구니에 등록되어 있는 경우 장바구니 리스트에 구매 불가 상품으로 표시가 필요합니다. (아래 이미지 참고)
■ [정기결제 다음배송일자 조회하기 API ](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-next-recurring-date)확인하기
```
GET /recurring-payments/next-recurring-date
정기결제 다음 배송일자를 조회하는 API 입니다.
```
해당 API를 호출하여, 예시 장바구니 화면 내 '정기배송 첫 배송 예정일' 을 구현할 수 있습니다.\
배송주기와 배송일, 배송요일을 기준으로 첫 정기배송일을 출력합니다.
계산 된 배송 예상일이 현재보다 +2일 이내인 경우, 다음 주기에 배송됩니다.
\
<참고사항>
* 배송 예정일 3일전
* 신청 상품이 결제 가능인 경우 (정상) : sms 또는 email 설정에 따라 정기결제 상품에 대해 결제 예정 내용을 발송 요청
* 신청 상품이 판매 불가인 경우 (비정상) : 정기결제 상품의 상태를 '시스템 해지(`SYSTEM_CLOSED`)' 로 강제 변경 (sms, email 발송 요청 없음)
* 배송 예정일 2일전
* 신청 상품이 결제 가능인 경우 (정상) : 주문서 생성 및 PG결제
* 신청 상품이 판매 불가인 경우 (비정상) : 정기결제 상품의 상태를 '시스템 해지(`SYSTEM_CLOSED)`' 로 강제 변경 (sms, email 발송 요청 없음)
* 신청 상품이 결제 불가인 경우 (비정상) : 주문서 생성 > 주문서 상태 결제 실패 처리 > 정기결제 상품의 상태를 '시스템 일시정지(`SYSTEM_PAUSED`)' 로 강제 변경 (sms, email 발송은 결제 실패 안내 설정 시 발송 요청)
\
\
■ [정기결제 장바구니 수정하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-cart) API 확인하기
```
PUT /recurring-payments/cart
장바구니 목록에서 장바구니를 수정하는 API 입니다.
```
장바구니 화면 내 구매 '수량'을 변경하는 API입니다.
\
\
■ [정기결제 장바구니 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/delete-recurring-payments-cart) API 확인하기
```
DELETE /recurring-payments/cart
장바구니 목록에서 장바구니를 삭제하는 API 입니다.
```
장바구니 화면 내 '삭제' 버튼 클릭 시 호출되는 API입니다.
\
\
■ [정기결제 장바구니에서 선택된 상품금액 계산하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart-calculate) API 확인하기
```
GET /recurring-payments/cart/calculate
장바구니에서 선택된 상품만 계산하여 금액을 응답하는 API 입니다.
```
장바구니에서 선택된 상품(cartNo) 금액을 계산합니다.\
cartNo은 `GET /cart`API 내 상품 옵션 별로 `orderProductOptions`에서 확인 가능합니다.
장바구니 리스트에서 좌측 체크박스에 '체크 된 항목이 변경될 때마다' 실시간으로 금액 정보를 계산합니다.
\
\
■ [정기결제 장바구니에서 선택된 항목만 그룹별로 재계산하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart-subset) API 확인하기
```
GET /recurring-payments/cart/subset
장바구니에서 선택된 상품만 계산하여 장바구니 상품정보와 금액을 함께 응답하는 API 입니다.
```
GET /recurring-payments/cart/calculate는 장바구니 목록에서 체크박스 체크/해제 시 선택된 상품의 금액정보만 재계산하여 내려주는 반면\
GET /recurring-payments/cart/subset은 금액정보 뿐 아니라, 배송 그룹별로 나뉜 상품정보까지 함께 내려준다는 차이가 있습니다.\
즉, 해당 API는 delievery groups에 대한 정보가 있어서, 장바구니 체크박스 체크/해제 시 배송그룹 조건으로 인한 배송비 변동(ex조건부 무료배송)도 함께 업데이트 가능합니다.
\
■ [정기결제 주문서 등록](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-order-sheets) API 확인하기
```
POST /recurring-payments/order-sheets
정기결제 주문을 진행할 상품정보를 전달하는 API입니다.
```
예시 장바구니 화면 내에서 '정기배송 신청' 버튼 클릭 시 호출하는 API로,\
장바구니 목록에서 체크박스 선택된 상품을 기준으로 정기결제 주문서를 생성합니다.
예시 화면 내 '바로구매'를 클릭할 경우에도, 해당 상품만을 기준으로 정기결제 주문서를 생성합니다.
참고로, 주문서에서 상품이 500원 미만이 된 경우 정기배송 신청 시 alert msg "유효하지 않은 정기결제 할인가가 적용되었습니다."를 출력하셔야합니다.
#### 3) 주문서 화면
\
■ [정기결제 주문서 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-order-sheets-order-sheets-no) API 확인하기
```
GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.
```
장바구니 화면에서 등록한 배송주기, 배송일, 배송요일, 첫배송 예정일, 정기결제 사은품을 출력합니다.
참고로 주문서 화면에 진입한 뒤, 정기결제가가 500원 미만으로 변경된 뒤 새로고침하면 에러가 발생합니다. (아래 이미지 참고)
\
\
■ [배송지 목록 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses) API 확인하기
```
GET /shop/profile/shipping-addresses
주소지 정보를 조회하는 API 입니다.
```
응답 값 내 `recurringPaymentAddresses (정기결제 배송지)` 필드값을 활용합니다.\
주문서 화면 내 배송지선택 항목은 미선택된 상태가 디폴트이고\
정기결제 신청 시 마다, 정기배송지 관리 레이어(아래 이미지 참고)에서 선택하도록 구현합니다.
\
■ [배송지 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/post-profile-shipping-addresses) API 확인하기
```
POST /profile/shipping-addresses
주소지 정보를 추가하는 API 입니다.
```
새 배송지를 추가하는 '배송지 추가버튼'을 구현할 수 있는 API입니다.\
배송지 추가 개수는 기존 배송지관리 화면과 동일하게 적용됩니다 ([가이드](https://shopby.works/guide/dev-cover/order#payment-info) 내 C.배송지 정보 참고)\
Request Body 내 `addressType 배송지타입` > `RECURRING_PAYMENT 정기결제 배송주소`를 통해 정기배송지 여부를 실어보냅니다.
\
\
■ [배송지 수정하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/put-profile-shipping-addresses-address-no) API 확인하기
```
PUT /shop/profile/shipping-addresses/{addressNo}
선택한 주소지 정보를 수정하는 API 입니다.
```
'수정버튼'을 구현할 수 있는 API입니다.\
Request Body 내 `addressType 배송지타입` > `RECURRING_PAYMENT 정기결제 배송주소`를 통해 정기배송지 여부를 실어보냅니다.\
단, 정기배송지로 등록된 배송지는 수정이 불가하며, "해당 배송주소로 신청된 정기배송 건이 있어 수정 불가합니다. 정기배송 해지 후 수정해주시기 바랍니다"와 같은 알럿메시지를 출력해야합니다.
\
\
■ [배송지 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/delete-profile-shipping-addresses-address-no) API 확인하기
```
DELETE /shop/profile/shipping-addresses/{addressNo}
등록한 주소지 정보를 삭제하는 API 입니다.
```
'삭제 버튼'을 구현할 수 있는 API입니다.\
호출 시 파라미터 내 `addressNo 배송지 번호`를 삭제하게 되는데, 해당 값은 정기배송지 여부와 상관없는 고유 값이므로 정기배송지 여부를 별도로 요청보내지 않는 점을 참고부탁드립니다.\
정기배송지로 등록된 배송지는 삭제 불가하며, 삭제가 불가하다는 알럿메시지를 출력해야합니다.
\
\
■ [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API 확인하기
```
GET /recurring-payments/cards
모든 정기결제 카드를 조회하는 API 입니다.
```
회원의 모든 정기결제 카드를 조회할 수 있습니다. (최대 5개)\
마이페이지> 정기배송관리 > 결제카드 관리 에 등록된 카드 정보를 출력합니다.\
회원에게 등록된 정기결제 카드가 없을 시 빈 리스트를 응답하며, 등록된 카드정보가 없는 경우 카드 등록 버튼을 노출해야합니다.
***
## 정기결제 카드 등록 방법 (KCP, KSNET)
정기결제 카드를 등록하는 방법은 두 가지 입니다. 사용하시는 PG사에 알맞은 방법을 택일해서 사용하세요.
* \[KCP] 정기결제 스크립트를 실행해서 등록하기
* [#kcp-ncp\_pay.js](#kcp-ncp_pay.js "mention")
* \[KSNET] 정기결제 카드 등록하기 API를 활용해 등록하기
* [#ksnet-api](#ksnet-api "mention")
***
### ■ **\[KCP]** 정기결제 스크립트 실행 방법 (ncp\_pay.js )
이를 구현하기 위해서는 결제모듈 javascript를 제공하고 있는데, (참고: 일반 결제 [결제편의모듈 가이드](https://workspace-help.nhn-commerce.com/aurora-skinguide/api-1/order-sheet-form#javascript))
정기결제 모듈을 실행하기 위해서는, KCP에서 정기결제용 PG key / siteCd / kcpGroupId 3가지 정보 발급받은 뒤 NHN커머스로 전달하여 세팅요청이 필요합니다.\
일반결제 KCP의 PG key가 이미 세팅되어 있더라도 정기결제용 PG key 별도 발급이 필요합니다.
\
\
`Step 1` **NCPPay 모듈 import**
* ncp\_pay.js 로드
```
```
\
\
`Step 2` **각 PG 사에서 제공하는 결제 모듈 javascript 를 로드**\
정기결제의 경우, 아래 KCP 모듈을 로드합니다.
```
const payScripts = {
real: [
'https://pay.kcp.co.kr/plugin/payplus_web.jsp'
],
};
```
\
\
`Step 3` **NCPPay.setConfiguration 값 입력**\
아래 설명을 참고하여 Configuration 값을 입력합니다.
```
NCPPay.setConfiguration({
'clientId': ncp.clientId, // shopby에서 발급받은 clientId
'confirmUrl': 'payment-confirm.html', // 결과를 리턴받을 url
'platform': 'PC', // 'PC or MOBILE_WEB or MOBILE_APP'
'shopbyAuthorization' : accessToken ? `Bearer ${accessToken}` : '', // Oauth2 인증 방식을 사용시 인증 헤더 구분 값
'accessToken': '', // Oauth 인증 방식을 사용시 인증 헤더 구분 값
});
```
\
참고로 `clienId`는, 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값입니다.\
(프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)
* 샵바이프로: `enviroment.json` 내 `clientId` 값으로 확인 가능합니다.
* 샵바이프리미엄: 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능합니다.
단, 각 PG에서 제공하는 아래와 같은 예시코드를 javascript코드로 입력해야합니다.
```
```
\
\
`Step 4` **NCPPay.reserveRecurringPaymentKey() 메소드 호출**
파라미터로 recurringPaymentRedirectUrl, successCallback, failCallback를 전달하면됩니다.
* `recurringPaymentRedirectUrl` : 진행 후 돌아올 URL
* `successCallback`: 성공 시 진행할 콜백 함수
* `failCallback`: 실패 시 진행할 콜백 함수
### ■ **\[KSNET]** [정기결제 카드 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-card) API 호출 방법
```
POST /recurring-payments/card
정기결제 카드를 등록하는 API 입니다.
사용중인 PG가 비 인증 방식으로 정기결제 카드를 등록하는 경우 사용 가능합니다.
```
위 API 를 호출하기 위해서는, KSNET에서 PG key를 발급받은 뒤 NHN커머스로 전달하여 세팅요청이 필요합니다.
\
■ [적용 중인 몰 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms) API 확인하기
```
GET /terms
해당 쇼핑몰의 약관을 조회하는 API 입니다.
```
파라미터 `REGULAR_PAYMENT_USE: 정기결제(배송) 이용약관` 과 `AUTO_APPROVAL_USE: 자동 승인 이용약관`를 활용하여,\
서비스 어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 이용약관 - 정기결제(배송) 이용약관/ 자동 승인 이용약관 내용을 출력합니다.
\
\
■ [정기결제 신청하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments) API 확인하기
```
POST /recurring-payments
정기결제를 신청하는 API입니다.
```
주문서 화면에서 최종적으로 '정기배송 신청'버튼 클릭 시 호출되는 API입니다.\
사은품 지급 가능 여부, 배송지 등록여부, 정기결제카드 등록여부 및 약관동의 여부 유효성 검사 후 정기결제를 신청합니다.\
메인카드로 사용할 카드번호를 입력하지 않으면, 회원의 가장 우선순위가 높은 카드가 메인카드로 지정됩니다.
* 카드가 등록되어있지 않거나 약관동의를 하지 않은 경우 알럿메시지를 출력해야합니다.
* 주문서 내부에서 결제하기 버튼 클릭 시, 500원인지 유효성 체크하여 알럿메시지를 출력해야합니다.
정기결제 신청 시, 서비스어드민>주문관리>정기결제(배송)신청 내역 관리 및\
고객 마이페이지> 정기배송관리> 정기배송 신청관리에 등록됩니다.
\
#### 3-1) 정기결제 주문완료 화면
정기배송 신청 완료 시 신청정보 확인하는 주문완료 화면입니다.\
위에서 소개드린 `POST /recurring-payments` 정기결제 신청하기 API 응답 값을 로컬스토리지에 잠시 저장하고 있다가, 주문완료 페이지 도달 시 사용합니다. (사용 후 로컬스토리지에서 제거)\
예시 화면에서는 상품별 신청정보와 상품명 및 배송지정보(배송지 관리에서 선택한 배송지의 받는사람,주소,휴대폰번호) 등을 출력하였습니다.
\
#### 4) 마이페이지 화면
\
#### 4-1) 마이페이지 > 주문목록/배송조회
■ [주문 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders) API 확인하기
```
GET /profile/orders
시작일 종료일 사이의 주문리스트를 조회하는 API 입니다.
```
마이페이지에서, 결제된 상품이 고객이 신청한 정기결제(배송) 상품인 경우 상품명 앞에 '정기배송 상품'임을 예시화면과 같이 출력할 수 있습니다.
참고로 매일 09시에 2일 뒤 배송 예정건에 대해 주문을 생성하므로 (ex. 정기배송 예정일이 25일이면 23일 09시에 주문생성)\
위와 같은 주문목록/배송목록은 배송예정일 2일전에 주문서 생성 시 조회할 수 있는 화면이며, 이 시점에 주문일자=결제일자로 화면이 조회됩니다.
\
#### 4-2) 마이페이지 > 정기배송 관리 > 정기배송 신청관리
■ [정기결제 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments) API 확인하기
```
GET /recurring-payments
정기결제를 조회하는 API입니다.
```
마이페이지 내 정기배송관리 메뉴에서, 정기결제 신청내역을 확인할 수 있습니다.\
참고로 \[배송일 / 배송지 / 카드번호] 가 동일한 경우에만 같은 주문으로 생성됩니다.
<참고>\
`statusType (정기결제 상태 타입)`
* 정기결제는 1가지의 상태만 갖습니다.
ACTIVE -> 이용중\
SYSTEM\_CLOSED -> 정기결제가 불가능한 상품 등의 이유로 시스템상에서 정기결제가 해지된 경우\
ADMIN\_CLOSED -> 관리자가 정기결제를 해지한 경우\
USER\_CLOSED -> 사용자가 직접 정기결제를 해지한 경우\
ROUND\_FINISHED -> 정기결제 종료회차가 도래하여 해지된 경우\
SYSTEM\_PAUSED -> 결제실패 등의 이유로 시스템상에서 정기결제가 일시정지된 경우\
ADMIN\_PAUSED -> 관리자가 정기결제를 일시정지한 경우\
USER\_PAUSED -> 사용자가 직접 정기결제를 일시정지한 경우
\
`nextActions (다음에 할 수 있는 작업)` -
* 정기결제는 다음 값에 해당하는 작업을 할 수 있습니다.
PAUSE -> 일시정지\
RESUME -> 일시정지 해제\
SKIP -> 회차 건너뛰기\
CHANGE\_DELIVERY\_INFO -> 배송정보 변경\
CHANGE\_GIFT\_INFO -> 사은품 정보 변경\
CLOSE -> 해지하기
\
`recurringPaymentGroupNo (정기결제 신청 그룹 번호)`
* 동시에 신청한 정기결제의 경우, 동일한 신청 그룹 번호를 갖습니다.
* `GET /order-configs` 응답값이 recurringPaymentFreeGiftIssueType = RECURRING\_PAYMENT\_GROUP\_NO 인 경우에만 유효한 값입니다.
\
\
■ [정기결제 상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-recurring-payment-id) API 확인하기
```
GET /recurring-payments/{recurringPaymentId}
정기 결제 상세 조회 API 입니다.
```
`배송정보 변경` 레이어를 띄우기 위한 값을 내려받을 수 있습니다.
\
■ [정기결제 배송정보 변경하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-delivery) API 확인하기
```
PUT /recurring-payments/{recurringPaymentId}/info
정기 결제 정보를 수정하는 API 입니다.
```
예시 화면 내 '배송정보 변경' 버튼 클릭 시 위와 같은 레이어를 통해 정기결제의 배송정보를 변경할 수 있습니다.\
변경을 원치 않는 정보는 null 로 요청해 주세요.\
서비스 어드민에서 정기결제 변경 히스토리를 조회할 수 있습니다.
**`1. 상품 변경`**\
상품 변경 시 새로운 배송 주기 정보도 같이 입력해야 합니다.\
상품 수정 시 변경되는 상품의 사은품으로 자동 변경됩니다.\
변경 버튼 클릭 시 [변경 가능한 정기 결제 상품 조회하기](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-regular-delivery) API를 호출하여 변경가능한 상품을 보여주세요.
\
\&#xNAN;**`2. 배송지 변경`**\
변경 할 정기 결제 주소지를 입력해야 합니다.\
변경 버튼 클릭 시 [배송지 목록 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses) API를 호출하여 변경가능한 배송지를 보여주세요.
\
\&#xNAN;**`3. 결제 정보 변경`**\
요청한 카드가 해당 정기 결제의 메인 카드가 됩니다.\
변경 버튼 클릭 시 [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API를 호출하여 변경가능한 카드를 보여주세요.
**`4. 배송 주기 변경`**\
정기 결제 상품에 대해 설정할 수 있는 배송 주기를 입력해야 합니다.\
위의 `정기결제 상세 조회` API 응답값의 adjustableDeliveryCycle 로 내려오는 값만 요청할 수 있습니다.
* 정기결제의 배송 주기를 변경하는 경우 변경 주기에 해당하는 날짜를 계산하여 `배송 예상일` 이 변경됩니다.
* 정기결제 배송 주기 변경 시 이전 배송일 기준으로 변경되는 주기에 해당하는 날짜를 계산 (A)
* 이전 배송일이 없는 경우 정기결제 최초 신청일이 기준이 됩니다.
* (A) 가 변경일을 기준으로 배송 가능한 날짜면 해당 날짜에 배송
* (A) 가 변경일을 기준으로 배송이 불가능하면, 변경일을 신청일로 보고 배송 예상일 계산
* 주기 변경일이 배송 예상일이 포함된 주/달인 경우 동일한 주/달에 중복 배송되는 현상을 방지하기 위해 한 주기 이후로 계산
* 정해진 `배송 예상일`에 배송이 된 후, 새로운 배송주기로 다음 `배송 예상일`이 계산됩니다.
\
\
\&#xNAN;**`5. 종료 회차 변경`**\
정기 결제의 종료 회차를 설정하지 않으려면 0으로 보내주세요.
\
\
■ [정기결제 상태 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-status) API 확인하기
```
PUT /recurring-payments/{recurringPaymentId}/status
정기결제의 상태를 변경하는 API 입니다.
```
아래와 같은 상태변경만 가능합니다.
이용중 (ACTIVE) -> 일시중지 (USER\_PAUSED)\
일시중지 (USER\_PAUSED) -> 이용중 (ACTIVE)
\
\
■ [정기결제 사은품 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-recurring-payment-id-gifts) API 확인하기
```
GET /recurring-payments/{recurringPaymentId}/gifts
정기 결제 사은품을 조회하는 API 입니다.
```
사은품 정보 변경 레이어를 띄우기 위한 값을 내려받을 수 있습니다.
\
\
■ [정기결제 사은품 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-gifts) API 확인하기
```
PUT /recurring-payments/gifts
정기 결제 사은품을 변경하는 API 입니다.
```
* 최초 정기결제 신청 시 선택할 수 있었던 사은품 중에서 선택할 수 있습니다.
* `GET /order-configs` 응답값이 recurringPaymentFreeGiftIssueType = RECURRING\_PAYMENT\_GROUP\_NO 인 경우\
recurringPaymentGroupNo 값이 동일한 정기결제들을 동시에 요청해주세요.
\
\
■ [정기결제 회차 건너뛰기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-skip-next) API 확인하기
```
POST /recurring-payments/{recurringPaymentId}/skip/next
정기결제의 다음 회차를 건너뛰도록 설정합니다.
```
회차 건너뛰기 설정 시, 돌아오는 배송 예정일에 결제가 이루어지지 않고 회차도 증가하지 않습니다.
\
\
■ [정기결제 해지하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-close-recurring-payment-no) API 확인하기
```
PUT /recurring-payments/close/{recurring-payment-no}
정기결제를 해지 처리하는 API 입니다.
```
예시화면 내 '해지하기'버튼 클릭 시 아래와 같은 레이어를 통해 closeReasonType(해지사유)를 선택할 수 있으며,\
'해지'버튼 클릭 시 해지여부에 대한 컨펌창 호출 후 고객 최종 확인을 거쳐 상태 값이 업데이트 됩니다.
#### 4-3) 마이페이지 > 정기배송관리 > 결제카드관리
\
\
■ [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API 확인하기
```
GET /recurring-payments/cards
정기결제 카드를 조회하는 API 입니다.
```
주문서 화면에서 이미 소개드린 API로, 등록된 카드정보를 출력합니다.\
만약 등록된 카드정보가 없을 경우 카드등록 버튼(아래 예시 참고)을 노출해야 합니다.\
카드등록은 주문서 화면의 정기결제 카드 등록 방법 (KCP, KSNET) 참고해주세요.
\
\
■ [정기결제 카드 우선순위 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-card) API 확인하기
```
PUT /recurring-payments/card/priority
정기결제 카드의 우선순위를 변경하는 API 입니다.
```
* 모든 카드의 우선순위를 입력해야 합니다.
* 정기결제에 실패하는 경우, 카드의 우선순위에 따라 다음으로 결제를 시도할 카드가 결정됩니다.
\
\
■ [정기결제 카드 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/delete-recurring-payments-card-card-no) API 확인하기
```
DELETE /recurring-payments/card/{cardNo}
정기결제 카드를 삭제하는 API 입니다.
```
정기결제 신청 상품이 모두 해지된 경우에만 카드삭제가 가능하며,\
만약 정기결제 상품이 있는 경우 "카드 정보를 삭제하시려면 정기배송 상품을 먼저 해지해주세요"와 같은 알럿이 출력되어야합니다.
\
\
■ [정기결제 메인 카드 설정](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-card-card-no-main) API 확인하기
```
PUT /recurring-payments/card/{cardNo}/main
정기결제 메인 카드를 설정하는 API 입니다.
```
* 메인 카드는 우선순위가 1로 설정됩니다.
\
\
#### 4-4) 마이페이지 > 배송지관리 > 정기배송지 관리
※마이페이지 내 정기배송지 관리화면 호출API는, 위 주문서 화면에서 이미 안내드린 내용과 동일합니다.