@portone/mcp-server 0.13.0

package/assets/docs/opi/ko/extra/promotion/intro.md

@@ -0,0 +1,31 @@
+---
+title: 프로모션
+description: 카드 즉시 할인을 쉽게 운영 및 관리할 수 있는 서비스입니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+## 프로모션이란?
+
+고객사가 카드사와 계약하여 사용자에게 즉시 할인을 제공하는 **카드 즉시 할인 서비스**를 운영하고 관리할
+수 있는 서비스 입니다.
+
+카드 즉시 할인 서비스를 이용시 필요한 **프로모션 관리 시스템**과 **프로모션 정산 대사 시스템** 을 제공합니다.
+포트원 콘솔에서 기간, 할인 조건, 예산 등 다양한 옵션의 프로모션을 설정할 수 있으며,
+생성된 프로모션 아이디를 포함하여 결제 요청시 즉시 할인을 적용할 수 있습니다.
+또한, 프로모션이 종료된 후 할인이 적용된 거래 건들만 모아 엑셀로 다운로드하여 한 번에 결제 내역 정리 및 정산 금액 대사를 할 수 있습니다.
+
+프로모션은 일부 고객사에 한하여 제공하고 있으며, 프로모션 도입을 원하시는 고객사의 경우 포트원으로 문의 주시기 바랍니다.
+
+<div class="hint" data-style="info">
+
+프로모션 메뉴의 경우 도입 고객사에 한하여 포트원 콘솔 내에서 확인하실 수 있습니다.
+
+</div>
+
+[프로모션 생성하기](https://developers.portone.io/opi/ko/extra/promotion/console-guide)
+
+[프로모션 결제 연동하기](https://developers.portone.io/opi/ko/extra/promotion/integration)
+
+[프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund)

package/assets/docs/opi/ko/extra/promotion/refund.md

@@ -0,0 +1,316 @@
+---
+title: 프로모션 결제 취소하기
+description: 프로모션을 적용하여 승인된 결제건들에 대하여 취소/환불하는 방법을 안내합니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+## 프로모션 결제 취소하기
+
+프로모션이 적용된 결제에 대해 결제 취소가 가능합니다.
+결제 취소 시 취소 정책에 따라 적용된 프로모션 금액 중 회수된 금액만큼 프로모션 예산 금액으로 복구됩니다.
+
+<div class="hint" data-style="info">
+
+콘솔에서 프로모션 생성시 설정한 **프로모션 예산 미복구** 옵션에 따라 예산 복구 여부가 결정됩니다.
+
+예산 복구를 원하지 않는 경우 프로모션 예산 미복구 옵션을 **활성화** 상태로 설정해 주세요.
+
+</div>
+
+<div class="hint" data-style="danger">
+
+결제 취소시 경우에 따라 결제 건이 프로모션 정책에 해당되지 않을 수 있습니다.
+이로 인해 취소 이후 잔여 승인 금액 (잔여 실 결제 금액)이 현재 잔여 승인 금액보다 커질 수 있으며, 이런 경우 취소가 불가능합니다.
+
+- ex) `10,000원 이상 결제 시 10% 할인` 프로모션을 적용한 후 10,000원을 결제 요청한 경우
+  실제 9,000원이 결제됩니다. 이후 500원을 취소 요청하게 되면 프로모션 정책에 해당하지 않게 되고,
+  실제 결제되어야 하는 금액이 9,500원이 되어야 합니다.
+  하지만 기존에 실제 승인된 금액이 9,000원이므로 이런 경우 결제 취소가 불가합니다.
+
+</div>
+
+<!-- VERSION-SPECIFIC: V1 ONLY CONTENT START -->
+
+### 예제 코드
+
+```ts
+// imp_uid, merchant_uid, amount, checksum, retain_promotion 등 정보를 전달받습니다.
+// 포트원 결제 취소 API 호출
+const onetimeResponse = await fetch("https://api.iamport.kr/payments/cancel", {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${ACCESS_TOKEN}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    imp_uid: `imp_XXXXXXXXXXXX`, // 포트원 고유 주문번호
+    merchant_uid: `order_id_XXXXXXXXXXXX`, // 고객사 주문번호
+    amount: number, // 취소 요청 금액
+    checksum: number, // 현 시점 취소 가능한 잔액
+    reason: "단순 변심", // 취소 사유
+    retain_promotion: boolean, // 프로모션 혜택 유지 여부
+    // 중략...
+  }),
+});
+```
+
+### 주요 파라미터
+
+- imp\_uid: string
+
+  **포트원 고유 주문번호**
+
+  - 취소할 결제건의 포트원 고유 주문번호를 전달합니다.
+  - `imp_uid`와 `merchant_uid` 둘 중 하나는 필수입니다.
+
+- merchant\_uid: string
+
+  **고객사 주문번호**
+
+  - 취소할 결제건의 결제 당시 설정한 고객사의 주문번호를 전달합니다.
+  - `imp_uid`와 `merchant_uid` 둘 중 하나는 필수입니다.
+
+- amount?: integer
+
+  **결제 취소 요청 금액**
+
+  - (부분)취소 요청 금액을 전달합니다.
+  - 미입력시 잔여 취소 가능 금액만큼 전체 취소됩니다.
+
+  <div class="hint" data-style="danger">
+
+  취소 요청 금액은 프로모션 적용 금액을 고려하지 않고 전달합니다.
+
+  ex) `10,000원 결제에 10% 할인` 프로모션이 적용되어 10,000을 결제 요청한 경우 실 승인 금액은 9,000원이고,
+  이에 대해 전체 취소를 요청하는 경우 `amount`는 `10000`으로 전달해야 합니다.
+
+  </div>
+
+- checksum?: integer
+
+  **현 시점 취소 가능한 잔액**
+
+  - 현 시점 취소 가능한 잔액을 전달합니다.
+  - 고객사의 계산 상 남아있는 잔여 금액과 포트원 내부 데이터 상 잔여 금액을 비교하며 불일치할 시 취소를 진행하지 않습니다.
+
+  <div class="hint" data-style="danger">
+
+  취소 요청 금액은 프로모션이 적용되지 않은 주문금액을 기준으로 전달합니다.
+
+  ex) 20,000원 결제에 10% 할인 프로모션이 적용된 결제(실 승인 금액은 18,000원)에 대해 `amount`를 `10000`로 하여 1차 부분취소 완료.(실 취소 승인 금액은 9,000원)
+
+  2차 부분 취소 시 `checksum`은 `10000`으로 전달.
+
+  </div>
+
+- reason?: string
+
+  **취소 사유**
+
+- retain\_promotion?: boolean
+
+  **프로모션 혜택 유지 여부**
+
+  - 프로모션 결제 취소 이후 잔여 금액이 프로모션 정책에 위반되더라도 정책을 계속해서 유지할지 여부를 전달합니다. (default: `false`)
+
+  <div class="hint" data-style="warning">
+
+  프로모션 할인이 적용된 거래 건을 여러번 부분 취소하는 경우 처음 선택한 취소 옵션으로만 가능합니다. 예를 들어 \[프로모션 혜택 유지]로 처음 부분 취소한 경우 동일 거래 건에 대해 부분 취소를 진행하는 경우 \[프로모션 혜택 유지] 옵션으로만 취소가 가능합니다.
+
+  </div>
+
+  - \<Parameter.Type>true\</Parameter.Type>
+
+    **프로모션 할인 혜택 유지**
+
+    부분 취소 후 남은 결제 금액이 원래 프로모션 적용 기준보다 낮아지더라도, 최초 적용된 할인 혜택을 그대로 유지합니다.
+    이 경우 최초 할인 적용 시 산출된 할인율 또는 할인액을 기준으로, 부분 취소 후 남은 주문금액에 동일 할인 비율을
+    재적용하여 최종 결제 금액을 계산합니다.
+
+    - **할인율 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 10% 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에 10% 할인 적용 → 최종 결제액: 6,000원 x 90% = 5,400원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 유지 옵션에 따라 10% 할인 재적용: 4,000원 x 10% = 400원 할인
+        4. 재계산 최종 결제액: 4,000원 - 400원 = 3,600원
+        5. **취소 요청 금액:** 5,400원 - 3,600원 = 1,800원
+
+    - **할인액 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 1,000원 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에서 1,000원 할인 적용 → 최종 결제액: 6,000원 - 1,000원 = 5,000원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 효과는 5,000원 기준으로 1,000원 할인, 즉 20% 할인으로 해석됨
+        4. 유지 옵션에 따라 20% 할인 재적용: 4,000원 x 20% = 800원 할인
+        5. 재계산 최종 결제액: 4,000원 - 800원 = 3,200원
+        6. **취소 요청 금액:** 5,000원 - 3,200원 = 1,800원
+
+  - \<Parameter.Type>false\</Parameter.Type>
+
+    **프로모션 할인 혜택 조정**
+
+    부분 취소 후 남은 주문금액이 원래 프로모션 적용 기준(예: 5천원 이상)에 미달하면, 할인 혜택이 제거되어
+    재적용되지 않습니다. 이 경우 남은 주문금액에서 할인 혜택을 적용하지 않고, 할인 미적용 금액 그대로 결제 금액을
+    산출합니다.
+
+    - **할인율 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 10% 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에 10% 할인 적용 → 최종 결제액: 6,000원 x 90% = 5,400원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 조건 미충족으로 할인 혜택 제거 → 재계산 최종 결제액: 4,000원
+        4. **취소 요청 금액:** 5,400원 - 4,000원 = 1,400원
+
+    - **할인액 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 1,000원 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에서 1,000원 할인 적용 → 최종 결제액: 6,000원 - 1,000원 = 5,000원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 조건 미충족으로 할인 혜택 제거 → 재계산 최종 결제액: 4,000원
+        4. **취소 요청 금액:** 5,000원 - 4,000원 = 1,000원
+
+<!-- VERSION-SPECIFIC: V1 ONLY CONTENT END -->
+
+<!-- VERSION-SPECIFIC: V2 ONLY CONTENT START -->
+
+### 예제 코드
+
+```ts
+import { GetPaymentError, PaymentClient } from "@portone/server-sdk/payment";
+
+const portone = PaymentClient({ secret: PORTONE_API_SECRET });
+
+async function cancelPayment() {
+  try {
+    // 포트원 결제 취소 API 호출
+    const cancelPaymentResponse = await portone.cancelPayment({
+      paymentId: "1234567890",
+      reason: "단순 변심",
+      amount: 1000,
+      promotionDiscountRetainOption: "RETAIN",
+    });
+    return cancelPaymentResponse;
+  } catch (e) {
+    if (e instanceof CancelPaymentError) {
+      return e.data;
+    }
+    throw e;
+  }
+}
+```
+
+### 주요 파라미터
+
+자세한 파라미터 구성은 [결제 취소 API 문서](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fcancel)를 참고해주시기 바랍니다.
+
+- paymentId: string
+
+  **결제 건 아이디**
+
+  - 취소할 결제건의 결제 아이디 입니다.
+
+- storeId?: string
+
+  **상점 아이디**
+
+  접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디로 취소 요청됩니다.
+
+- amount?: integer
+
+  **결제 취소 요청 금액**
+
+  - (부분)취소 요청 금액을 전달합니다.
+  - 미입력시 잔여 취소 가능 금액만큼 전체 취소됩니다.
+
+  <div class="hint" data-style="danger">
+
+  취소 요청 금액은 프로모션이 적용되지 않은 주문금액을 기준으로 전달합니다.
+
+  ex) `10,000원 결제에 10% 할인` 프로모션이 적용되어 10,000을 결제 요청한 경우 실 승인 금액은 9,000원이고,
+  이에 대해 전체 취소를 요청하는 경우 `amount`는 `10000`으로 전달해야 합니다.
+
+  </div>
+
+- reason?: string
+
+  **취소 사유**
+
+- promotionDiscountRetainOption?: <>
+  &#x20; \<Parameter.Type>"RETAIN"\</Parameter.Type>
+  &#x20; {" | "}
+  &#x20; \<Parameter.Type>"RELEASE"\</Parameter.Type>
+  \</>
+
+  **프로모션 혜택 유지 여부**
+
+  - 프로모션 결제 취소 이후 잔여 금액이 프로모션 정책에 위반되더라도 정책을 계속해서 유지할지 여부를 전달합니다. (기본값: "RELEASE")
+
+  <div class="hint" data-style="warning">
+
+  프로모션 할인이 적용된 거래 건을 여러번 부분 취소하는 경우 처음 선택한 취소 옵션으로만 가능합니다.
+  예를 들어 \[프로모션 혜택 유지]로 처음 부분 취소한 경우 동일 거래 건에 대해 부분 취소를 진행하는 경우 \[프로모션 혜택 유지] 옵션으로만 취소가 가능합니다.
+
+  </div>
+
+  - \<Parameter.Type>"RETAIN"\</Parameter.Type>
+
+    **프로모션 할인 혜택 유지**
+
+    부분 취소 후 남은 결제 금액이 원래 프로모션 적용 기준보다 낮아지더라도, 최초 적용된 할인 혜택을 그대로 유지합니다.
+    이 경우 최초 할인 적용 시 산출된 할인율 또는 할인액을 기준으로, 부분 취소 후 남은 주문금액에 동일 할인 비율을
+    재적용하여 최종 결제 금액을 계산합니다.
+
+    - **할인율 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 10% 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에 10% 할인 적용 → 최종 결제액: 6,000원 x 90% = 5,400원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 유지 옵션에 따라 10% 할인 재적용: 4,000원 x 10% = 400원 할인
+        4. 재계산 최종 결제액: 4,000원 - 400원 = 3,600원
+        5. **취소 요청 금액:** 5,400원 - 3,600원 = 1,800원
+
+    - **할인액 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 1,000원 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에서 1,000원 할인 적용 → 최종 결제액: 6,000원 - 1,000원 = 5,000원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 효과는 5,000원 기준으로 1,000원 할인, 즉 20% 할인으로 해석됨
+        4. 유지 옵션에 따라 20% 할인 재적용: 4,000원 x 20% = 800원 할인
+        5. 재계산 최종 결제액: 4,000원 - 800원 = 3,200원
+        6. **취소 요청 금액:** 5,000원 - 3,200원 = 1,800원
+
+  - \<Parameter.Type>"RELEASE"\</Parameter.Type>
+
+    **프로모션 할인 혜택 조정**
+
+    부분 취소 후 남은 주문금액이 원래 프로모션 적용 기준보다 낮아지면, 할인 혜택이 제거됩니다 .
+    이 경우 남은 주문금액에서 할인 혜택을 적용하지 않고, 할인 미적용 금액 그대로 결제 금액을 산출합니다.
+
+    - **할인율 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 10% 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에 10% 할인 적용 → 최종 결제액: 6,000원 x 90% = 5,400원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 조건 미충족으로 할인 혜택 제거 → 재계산 최종 결제액: 4,000원
+        4. **취소 요청 금액:** 5,400원 - 4,000원 = 1,400원
+
+    - **할인액 적용 예시:**
+      - **조건:** '5천원 이상 결제 시 1,000원 할인'
+
+      - **처리:**
+        1. 주문금액 6,000원에서 1,000원 할인 적용 → 최종 결제액: 6,000원 - 1,000원 = 5,000원
+        2. 2,000원 부분 취소 시 남은 주문금액: 6,000원 - 2,000원 = 4,000원
+        3. 할인 조건 미충족으로 할인 혜택 제거 → 재계산 최종 결제액: 4,000원
+        4. **취소 요청 금액:** 5,000원 - 4,000원 = 1,000원
+
+<!-- VERSION-SPECIFIC: V2 ONLY CONTENT END -->

package/assets/docs/opi/ko/extra/smart-routing/console-guide.md

@@ -0,0 +1,73 @@
+---
+title: 스마트 라우팅 - 콘솔 가이드
+description: 멀티PG 환경을 클릭 한 번으로 쉽게 만들 수 있는 결제 트래픽 분산 자동화 서비스 입니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+<div class="hint" data-style="info">
+
+스마트 라우팅 기능이 궁금하다면 [스마트 라우팅 기능 소개](https://developers.portone.io/opi/ko/extra/smart-routing/intro)를 확인해 보세요!
+
+</div>
+
+## 스마트 라우팅 그룹 생성하기
+
+스마트 라우팅을 사용하기 위해서는 포트원 관리자콘솔 내 \[연동 관리] - \[스마트 라우팅]에서 그룹 설정이 필요합니다.
+
+1. (관련 이미지 첨부)
+
+   포트원 콘솔 내에서 \[연동 관리] - \[스마트 라우팅]을 클릭하세요.
+
+2. \[스마트 라우팅 그룹 생성하기]를 클릭하세요.
+
+3. (관련 이미지 첨부)
+
+   연동할 환경을 선택하세요. \[실연동], \[테스트] 선택 시 해당 환경으로 등록된 채널만 표시됩니다.
+   스마트 라우팅 그룹 내에 동일한 환경의 채널끼리만 설정이 가능합니다.
+
+4. \[그룹 이름]은 필수로 입력해야 합니다. 그룹 이름은 별칭과 같이 사용되므로 그룹의 특징을
+   잘 나타내는 이름으로 작성하시길 권장드립니다.
+
+5. \[그룹 아이디]의 경우 그룹 생성 후 자동으로 채번되며, 결제 요청 시 사용됩니다.
+
+6. \[+채널 추가]를 클릭하세요.
+
+7. (관련 이미지 첨부)
+
+   그룹에 사용할 채널을 선택하세요. [지원 PG사 확인 바로가기](https://developers.portone.io/opi/ko/extra/smart-routing/intro?v=v2#사용-가능한-pg사-및-결제수단-)
+
+8. 채널은 최소 1개부터 최대 10개까지 설정이 가능합니다.
+
+9. 채널 추가 후 **비활성화** 하는 경우 해당 채널은 입력된 비율과 상관없이 라우팅 시 배제됩니다.
+
+10. 비율의 합은 100% 미만이거나 초과될 수 없습니다. 총 합이 100%여야만 합니다.
+
+11. 채널 설정을 완료하였으면 \[저장] 버튼을 클릭하여 그룹을 생성합니다.
+
+## 스마트 라우팅 그룹 수정하기
+
+1. (관련 이미지 첨부)
+
+   생성된 그룹은 위와 같이 표시됩니다.
+
+2. 그룹 설정을 변경하고 싶으신 경우 해당 그룹을 클릭하세요.
+
+3. (관련 이미지 첨부)
+
+   이미 생성된 그룹 내에서 결제대행사를 추가 혹은 삭제할 수 있습니다.
+
+4. 결제대행사별 비율을 변경할 수 있습니다.
+
+5. \[예약 시간 설정]을 체크한 후 시간을 설정하면 변경 시점을 예약할 수 있습니다. 예약 시간은 시간 단위로
+   선택 가능하며, 미래 시점으로만 예약할 수 있습니다.
+
+6. 즉시 적용을 원하시는 경우 \[예약 시간 설정]을 체크하지 않은 채 \[저장]을 클릭하세요.
+
+## 스마트 라우팅 그룹 삭제하기
+
+1. 수정 모드에서 \[그룹 삭제]를 클릭하세요.
+
+2. 삭제된 그룹은 복원되지 않으며, 결제 요청 파라미터 변경 없이 그룹을 삭제하는 경우 결제가
+   원활하지 않을 수 있습니다. 삭제 시 신중히 진행하시길 권장드립니다.