portone-io · sso-ashley · Nov 15, 2024
@@ -1,7 +1,7 @@
 ---
 title: 프로모션 결제 취소하기
 description: 프로모션을 적용하여 승인된 결제건들에 대하여 취소/환불하는 방법을 안내합니다.
-targetVersions: ["v1"]
+targetVersions: ["v1","v2"]
 ---
 
 import Details from "~/components/gitbook/Details";
@@ -11,22 +11,22 @@ import Hint from "~/components/Hint";
 ## 프로모션 결제 취소하기
 
 프로모션이 적용된 결제에 대해 결제 취소가 가능합니다.
-결제 취소 시 차감되었던 프로모션 예산은 다시 정책에 알맞게 조정되어 취소 후 잔여 금액에 적용되어야하는 프로모션 금액만큼을
-제한 만큼 복구됩니다.
+결제 취소 시 취소 정책에 따라 적용된 프로모션 금액 중 회수된 금액만큼 프로모션 예산 금액으로 복구됩니다.
 
 <Hint style="info">
-  콘솔에서 설정한 **프로모션 예산 미복구** 옵션에 따라 복구 여부가 작동합니다.
+  콘솔에서 프로모션 생성시 설정한 **프로모션 예산 미복구** 옵션에 따라 예산 복구 여부가 결정됩니다.
 
-  예산 복구를 원하지 않으실 경우 프로모션 예산 미복구 옵션을 활성화 시켜주세요.
+  예산 복구를 원하지 않는 경우 프로모션 예산 미복구 옵션을 **활성화** 상태로 설정해 주세요.
 </Hint>
 
 <Hint style="danger">
-  결제 취소 이후 잔여 요청 금액이 프로모션 정책에 위반되고 이로 인해 취소 이후 잔여 승인 금액이 현재 잔여 승인 금액보다 커지는 경우가 존재합니다.
+  결제 취소시 경우에 따라 결제 건이 프로모션 정책에 해당되지 않을 수 있습니다.
+  이로 인해 취소 이후 잔여 승인 금액 (잔여 실 결제 금액)이 현재 잔여 승인 금액보다 커질 수 있으며, 이런 경우 취소가 불가능합니다.
 
-  해당 경우 취소가 불가능합니다.
-
-  - ex) `10,000원 이상 결제 시 10% 할인` 프로모션으로 10,000원 결제 이후 500원 취소 요청.
-    취소 시 프로모션 정책에 위반되어 잔여 승인 금액이 9,500원이어야하지만 최초 실 승인 금액이 9,000원이므로 취소 불가.
+  - ex) `10,000원 이상 결제 시 10% 할인` 프로모션을 적용한 후 10,000원을 결제 요청한 경우
+  실제 9,000원이 결제됩니다. 이후 500원을 취소 요청하게 되면 프로모션 정책에 해당하지 않게 되고,
+  실제 결제되어야 하는 금액이 9,500원이 되어야 합니다.
+  하지만 기존에 실제 승인된 금액이 9,000원이므로 이런 경우 결제 취소가 불가합니다.
 </Hint>
 
 <VersionGate v="v1">
@@ -79,7 +79,8 @@ import Hint from "~/components/Hint";
   <Hint style="danger">
     취소 요청 금액은 프로모션 적용 금액을 고려하지 않고 전달합니다.
 
-    ex) 10,000원 결제에 10% 할인 프로모션이 적용된 결제(실 승인 금액은 9,000원)에 대해 전체 취소 시 `amount`는 `10000`으로 전달.
+    ex) `10,000원 결제에 10% 할인` 프로모션이 적용되어 10,000을 결제 요청한 경우 실 승인 금액은 9,000원이고,
+    이에 대해 전체 취소를 요청하는 경우 `amount`는 `10000`으로 전달해야 합니다.
   </Hint>
 
   **`checksum`** <mark style="color:purple;">**integer**</mark>
@@ -90,7 +91,7 @@ import Hint from "~/components/Hint";
   - 고객사의 계산 상 남아있는 잔여 금액과 포트원 내부 데이터 상 잔여 금액을 비교하며 불일치할 시 취소를 진행하지 않습니다.
 
   <Hint style="danger">
-    취소 가능한 잔액 역시 프로모션 적용 금액을 고려하지 않고 전달합니다.
+    취소 요청 금액은 프로모션이 적용되지 않은 주문금액을 기준으로 전달합니다.
 
     ex) 20,000원 결제에 10% 할인 프로모션이 적용된 결제(실 승인 금액은 18,000원)에 대해 `amount`를 `10000`로 하여 1차 부분취소 완료.(실 취소 승인 금액은 9,000원)
 
@@ -125,3 +126,73 @@ import Hint from "~/components/Hint";
     </Details.Content>
   </Details>
 </VersionGate>
+
+<VersionGate v="v2">
+  ### 예제 코드
+
+  ```ts
+  // paymentId, amount, promotionDiscountRetainOption 등 정보를 전달받습니다.
+  // 포트원 결제 취소 API 호출
+  const onetimeResponse = await fetch(
+    `https://api.portone.io/payments/${paymentId}/cancel`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `PortOne ${PORTONE_API_SECRET}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        amount: number, // 취소 요청 금액
+        reason: "단순 변심", // 취소 사유
+        promotionDiscountRetainOption: boolean, // 프로모션 혜택 유지 여부
+        // 중략...
+      }),
+    },
+  );
+  ```
+
+  ### 주요 파라미터
+
+  **`amount`** <mark style="color:purple;">**integer**</mark>
+
+  **결제 취소 요청 금액**
+
+  - (부분)취소 요청 금액을 전달합니다.
+  - 미입력시 잔여 취소 가능 금액만큼 전체 취소됩니다.
+
+  <Hint style="danger">
+    취소 요청 금액은 프로모션이 적용되지 않은 주문금액을 기준으로 전달합니다.
+
+    ex) `10,000원 결제에 10% 할인` 프로모션이 적용되어 10,000을 결제 요청한 경우 실 승인 금액은 9,000원이고,
+    이에 대해 전체 취소를 요청하는 경우 `amount`는 `10000`으로 전달해야 합니다.
+  </Hint>
+
+  **`reason`** <mark style="color:green;">**string**</mark>
+
+  **취소 사유**
+
+  **`promotionDiscountRetainOption`** <mark style="color:orange;">**boolean**</mark>
+
+  **프로모션 혜택 유지 여부**
+
+  - 프로모션 결제 취소 이후 잔여 금액이 프로모션 정책에 위반되더라도 정책을 계속해서 유지할지 여부를 전달합니다. (default: `false`)
+
+  <Hint style="warning">
+    프로모션 할인이 적용된 거래 건을 여러번 부분 취소하는 경우 처음 선택한 취소 옵션으로만 가능합니다.
+    예를 들어 \[프로모션 혜택 유지]로 처음 부분 취소한 경우 동일 거래 건에 대해 부분 취소를 진행하는 경우 \[프로모션 혜택 유지] 옵션으로만 취소가 가능합니다.
+  </Hint>
+
+  <Details>
+    <Details.Summary> 프로모션 혜택 유지 여부 예시 </Details.Summary>
+
+    <Details.Content>
+      - 프로모션 혜택 유지 (`true`): 결제 부분 취소시 잔여 결제 금액이 할인 적용 기준 금액보다 적더라도 프로모션 할인 혜택이 그대로 유지됩니다. 할인 혜택을 동일한 수준으로 유지하기 위해 기존에 적용된 할인 조건을 할인율로 환산하여 적용하게 됩니다.
+        - ex1) 프로모션 할인 조건이 `5천원 이상 결제시 10% 할인`일 때, 6000원 결제 요청시 프로모션 할인이 적용되어 5400원이 실제 결제됩니다. 이 때, 2000원 부분 취소시 **프로모션 혜택 조정** 옵션을 선택한 경우 프로모션 조건에 부합하지 않아 실제 1400원이 결제 취소 요청되며, 결제 완료 금액은 4000원이 됩니다.
+        - ex2) 프로모션 할인 조건이 `5천원 이상 결제시 1000원 할인`일 때, 6000원 결제 요청시 프로모션 할인이 적용되어 5000원이 실제 결제됩니다. 이 때, 2000원 부분 취소시 **프로모션 혜택 조정** 옵션을 선택한 경우 프로모션 조건에 부합하지 않아 실제 1000원이 결제 취소 요청되며, 결제 완료 금액은 4000원이 됩니다.
+
+      - 프로모션 혜택 조정 (`false`) : 결제 부분 취소시 잔여 결제 금액이 할인 적용 기준 금액보다 적은 경우 잔여 결제 금액에 맞추어 프로모션 할인 금액이 차감되어 적용됩니다.
+        - ex1) 프로모션 할인 조건이 `5천원 이상 결제시 10% 할인`일 때, 6000원 결제 요청시 프로모션 할인이 적용되어 5400원이 실제 결제됩니다. 이 때, 2000원 부분 취소시 **프로모션 혜택 유지** 옵션을 선택한 경우 실제 1800원이 결제 취소 요청되며, 결제 완료 금액은 3600원이 됩니다. (주문금액 6000원에서 2000원 부분 취소시 주문금액은 4000원이며 기존 할인 조건인 10% 할인이 유지되어 실 결제 금액은 3600원이 됩니다.)
+        - ex2) 프로모션 할인 조건이 `5천원 이상 결제시 1000원 할인`일 때 6000원 결제 요청시 프로모션 할인이 적용되어 5000원이 실제 결제됩니다. 이 때, 2000원 부분 취소시 **프로모션 혜택 유지** 옵션을 선택한 경우 실제 1800원이 결제 취소 요청되며, 결제 완료 금액은 3200원이 됩니다. (본 예시에서 기존에 적용된 할인 조건인 5천원 이상 결제시 1000원 할인은 20% 할인으로 환산됩니다. 주문금액 6000원에서 2000원 부분 취소시 남은 주문금액은 4000원이므로, 취소 이후 결제 완료 금액은 3200원이 되고 실제 취소 금액은 1800원이 됩니다.)
+    </Details.Content>
+  </Details>
+</VersionGate>