Skip to content

[FEAT] 환불 멱등성 키 + 중복 환불 방지 #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
unifolio0 merged 6 commits into from
Mar 3, 2026
Merged

[FEAT] 환불 멱등성 키 + 중복 환불 방지 #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c7f824d
refactor: 환불 로직 멱등성 키 추가
unifolio0 Mar 3, 2026
fd2ae35
chore: 토스 결제 상태 주석 추가
unifolio0 Mar 3, 2026
bf55562
refactor: 결제 취소 분산락 추가
unifolio0 Mar 3, 2026
6f1d5b7
refactor: 결제 취소 재시도 로직 추가
unifolio0 Mar 3, 2026
67e5efd
refactor: 사용자의 동일 요청에 대해 동일한 멱등키를 생성하도록 수정
unifolio0 Mar 3, 2026
6964c9b
test: 모킹 값 수정
unifolio0 Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/main/java/com/samhap/kokomen/interview/service/ResumeBasedInterviewService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.samhap.kokomen.interview.service;

import com.samhap.kokomen.global.annotation.DistributedLock;
import com.samhap.kokomen.global.exception.BadRequestException;
import com.samhap.kokomen.global.exception.ForbiddenException;
import com.samhap.kokomen.global.exception.UnauthorizedException;
Expand All @@ -21,7 +22,6 @@
import com.samhap.kokomen.resume.domain.MemberResume;
import com.samhap.kokomen.resume.repository.MemberPortfolioRepository;
import com.samhap.kokomen.resume.repository.MemberResumeRepository;
import com.samhap.kokomen.global.annotation.DistributedLock;
import com.samhap.kokomen.token.service.TokenFacadeService;
import java.util.List;
import lombok.RequiredArgsConstructor;
Expand Down
15 changes: 7 additions & 8 deletions src/main/java/com/samhap/kokomen/payment/domain/TosspaymentsStatus.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
package com.samhap.kokomen.payment.domain;

public enum TosspaymentsStatus {
READY,
IN_PROGRESS,
WAITING_FOR_DEPOSIT,
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

WAITING_FOR_DEPOSIT 상태가 제거되었습니다. 이 상태가 더 이상 사용되지 않거나 다른 방식으로 처리되는지 확인이 필요합니다. 만약 이 상태를 사용하는 기존 로직이 있다면, 예기치 않은 동작이나 데이터 불일치가 발생할 수 있습니다. 제거된 이유와 시스템 전반에 미치는 영향에 대한 설명이 추가되면 좋을 것 같습니다.

DONE,
CANCELED,
PARTIAL_CANCELED,
ABORTED,
EXPIRED
READY, // 결제 준비
IN_PROGRESS, // 결제 진행 중
DONE, // 승인 성공
CANCELED, // 결제 취소
PARTIAL_CANCELED, // 결제 부분 취소
ABORTED, // 승인 실패
EXPIRED // 유효 시간 만료
Comment on lines +4 to +10
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

Toss Payments API payment status values WAITING_FOR_DEPOSIT official documentation

💡 Result:

In the Toss Payments Core API Payment object, the status field can be one of these values:

  • READY
  • IN_PROGRESS
  • WAITING_FOR_DEPOSIT (virtual account only; issued account but customer hasn’t deposited yet)
  • DONE
  • CANCELED
  • PARTIAL_CANCELED
  • ABORTED
  • EXPIRED (after 30 minutes if not confirmed from IN_PROGRESS) [1]

WAITING_FOR_DEPOSIT is officially documented as: a status that exists only in the virtual account payment flow, when the issued virtual account has not yet received the customer’s deposit. [1]

Sources

  • [1] Toss Payments Developer Center — Core API Reference (Payment object status enum): (docs.tosspayments.com)

Citations:

🏁 Script executed:

# 파일 위치 확인 및 TosspaymentsStatus enum 전체 내용 조회
find . -name "TosspaymentsStatus.java" -type f

Repository: samhap-soft/kokomen-backend

Length of output: 144

🏁 Script executed:

# TosspaymentsStatus enum의 전체 코드와 enum 상수 확인
cat -n "src/main/java/com/samhap/kokomen/payment/domain/TosspaymentsStatus.java"

Repository: samhap-soft/kokomen-backend

Length of output: 396

🏁 Script executed:

# TosspaymentsStatus enum이 사용되는 모든 위치 찾기 (역직렬화, 매핑 등)
rg "TosspaymentsStatus" --type java -B 2 -A 2

Repository: samhap-soft/kokomen-backend

Length of output: 24524

🏁 Script executed:

# Toss Payments 관련 설정, API 모델, 응답 처리 확인
fd -t f -e java . -path "*toss*" -o -path "*payment*" | head -20

Repository: samhap-soft/kokomen-backend

Length of output: 239

가상계좌 결제 시 WAITING_FOR_DEPOSIT 상태 반환으로 역직렬화 실패 가능

Toss Payments API는 공식 문서에 WAITING_FOR_DEPOSIT를 정당한 결제 상태로 정의하고 있습니다(가상계좌 결제에서 계좌 발급 후 입금 대기 상태). 현재 enum에서 이 상태가 누락되어 있어, 해당 결제 방식 응답이 역직렬화되지 않습니다. 특히 웹훅 및 결제 조회 API 응답 처리 시 예외가 발생합니다.

🔧 수정 방안 
 public enum TosspaymentsStatus {
     READY, // 결제 준비
     IN_PROGRESS, // 결제 진행 중
+    WAITING_FOR_DEPOSIT, // 입금 대기 (가상계좌 등)
     DONE, // 승인 성공
     CANCELED, // 결제 취소
     PARTIAL_CANCELED, // 결제 부분 취소
     ABORTED, // 승인 실패
     EXPIRED // 유효 시간 만료
 }
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/main/java/com/samhap/kokomen/payment/domain/TosspaymentsStatus.java`
around lines 4 - 10, TosspaymentsStatus enum is missing the WAITING_FOR_DEPOSIT
value which causes deserialization failures for virtual account responses; add a
new enum constant WAITING_FOR_DEPOSIT (with an appropriate comment like "가상계좌 입금
대기") to the TosspaymentsStatus enum so incoming API/webhook payloads that
contain that state deserialize correctly, and run/update unit/integration tests
that deserialize Toss Payments responses to verify no exceptions occur.

Copy link
Copy Markdown
Contributor Author

@unifolio0 unifolio0 Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

저희 서비스는 가상계좌 결제 기능을 제공하지 않기로 결정했습니다.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@unifolio0, 알겠습니다! 가상계좌 결제 기능을 제공하지 않는다면 WAITING_FOR_DEPOSIT 상태를 enum에서 제거하는 것이 맞습니다. 비즈니스 요구사항을 반영한 적절한 결정입니다.

✏️ Learnings added 
Learnt from: unifolio0
Repo: samhap-soft/kokomen-backend PR: 341
File: src/main/java/com/samhap/kokomen/payment/domain/TosspaymentsStatus.java:4-10
Timestamp: 2026-03-03T06:01:32.009Z
Learning: kokomen-backend 프로젝트는 가상계좌 결제 기능을 제공하지 않으므로, TosspaymentsStatus enum에 WAITING_FOR_DEPOSIT 상태가 필요하지 않습니다.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

}
4 changes: 3 additions & 1 deletion src/main/java/com/samhap/kokomen/payment/external/TosspaymentsClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,12 @@ public TosspaymentsPaymentResponse confirmPayment(TosspaymentsConfirmRequest req

public TosspaymentsPaymentResponse cancelPayment(
String paymentKey,
TosspaymentsPaymentCancelRequest request
TosspaymentsPaymentCancelRequest request,
String idempotencyKey
) {
return restClient.post()
.uri("/v1/payments/{paymentKey}/cancel", paymentKey)
.header("Idempotency-Key", idempotencyKey)
.body(request)
.retrieve()
.body(TosspaymentsPaymentResponse.class);
Expand Down
20 changes: 16 additions & 4 deletions src/main/java/com/samhap/kokomen/payment/service/PaymentFacadeService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.samhap.kokomen.payment.service;

import com.samhap.kokomen.global.annotation.DistributedLock;
import com.samhap.kokomen.global.exception.BadRequestException;
import com.samhap.kokomen.global.exception.InternalServerErrorException;
import com.samhap.kokomen.global.exception.KokomenException;
Expand All @@ -15,8 +16,8 @@
import com.samhap.kokomen.payment.service.dto.CancelRequest;
import com.samhap.kokomen.payment.service.dto.ConfirmRequest;
import com.samhap.kokomen.payment.service.dto.PaymentResponse;
import com.samhap.kokomen.global.annotation.DistributedLock;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;
import java.util.UUID;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
Expand Down Expand Up @@ -54,7 +55,8 @@ public PaymentResponse confirmPayment(ConfirmRequest request) {

private TosspaymentsPaymentResponse confirmPayment(ConfirmRequest request,
TosspaymentsPayment tosspaymentsPayment) {
String idempotencyKey = UUID.randomUUID().toString();
String idempotencyKey = UUID.nameUUIDFromBytes(
("confirm:" + request.paymentKey()).getBytes(StandardCharsets.UTF_8)).toString();
try {
TosspaymentsPaymentResponse tosspaymentsConfirmResponse = tosspaymentsConfirmRetryTemplate.execute(
context -> {
Expand Down Expand Up @@ -139,12 +141,22 @@ private void handleConfirmNetworkError(ResourceAccessException e, TosspaymentsPa
tosspaymentsPaymentService.updateState(tosspaymentsPayment.getId(), PaymentState.NEED_CANCEL);
}

@DistributedLock(prefix = "payment", key = "#request.paymentKey()")
public void cancelPayment(CancelRequest request) {
TosspaymentsPaymentCancelRequest tosspaymentsPaymentCancelRequest = new TosspaymentsPaymentCancelRequest(
request.cancelReason());
String idempotencyKey = UUID.nameUUIDFromBytes(
("cancel:" + request.paymentKey()).getBytes(StandardCharsets.UTF_8)).toString();
try {
TosspaymentsPaymentResponse response = tosspaymentsClient.cancelPayment(request.paymentKey(),
tosspaymentsPaymentCancelRequest);
TosspaymentsPaymentResponse response = tosspaymentsConfirmRetryTemplate.execute(
context -> {
if (context.getRetryCount() > 0) {
log.warn("토스페이먼츠 환불 승인 재시도 {}회차, paymentKey = {}",
context.getRetryCount(), request.paymentKey());
}
return tosspaymentsClient.cancelPayment(request.paymentKey(),
tosspaymentsPaymentCancelRequest, idempotencyKey);
});
Comment on lines +151 to +159
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

RetryTemplate 재사용은 적절하나, 네이밍 불일치에 주의하세요.

tosspaymentsConfirmRetryTemplate을 취소 로직에도 재사용하고 있습니다. 재시도 정책이 confirm과 cancel에 동일하게 적용되어야 한다면 문제없지만, 향후 두 작업의 재시도 정책을 분리해야 할 경우 별도 템플릿이 필요할 수 있습니다.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/main/java/com/samhap/kokomen/payment/service/PaymentFacadeService.java`
around lines 151 - 159, The cancel call is reusing
tosspaymentsConfirmRetryTemplate which ties confirm and cancel retry behavior
together; if cancel needs a different retry policy, create a separate
RetryTemplate (e.g., tosspaymentsCancelRetryTemplate) and use it for the cancel
invocation instead of tosspaymentsConfirmRetryTemplate in the block that calls
tosspaymentsClient.cancelPayment(request.paymentKey(),
tosspaymentsPaymentCancelRequest, idempotencyKey); otherwise, add a comment near
tosspaymentsConfirmRetryTemplate explaining intentional reuse so future
maintainers know the choice.

tosspaymentsTransactionService.applyCancelResult(response);
} catch (HttpClientErrorException e) {
Failure failure = e.getResponseBodyAs(Failure.class);
Expand Down
13 changes: 7 additions & 6 deletions src/test/java/com/samhap/kokomen/payment/service/PaymentFacadeServiceTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@ class PaymentFacadeServiceTest extends BaseTest {
"cancel_tx_key", 9091L, 909L, 0L, 0L, true,
"{}", null, null, null, "KR", null, List.of(cancel)
);
when(tosspaymentsClient.cancelPayment(any(), any())).thenReturn(cancelResponse);
when(tosspaymentsClient.cancelPayment(any(), any(), any())).thenReturn(cancelResponse);

paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심"));

Expand All @@ -317,9 +317,10 @@ class PaymentFacadeServiceTest extends BaseTest {
@Test
void 결제_취소_시_400_에러가_발생하면_BadRequestException을_던진다() {
HttpClientErrorException clientError = mock(HttpClientErrorException.class);
when(clientError.getStatusCode()).thenReturn(HttpStatus.BAD_REQUEST);
when(clientError.getResponseBodyAs(Failure.class))
.thenReturn(new Failure("ALREADY_CANCELED_PAYMENT", "이미 취소된 결제입니다."));
when(tosspaymentsClient.cancelPayment(any(), any())).thenThrow(clientError);
when(tosspaymentsClient.cancelPayment(any(), any(), any())).thenThrow(clientError);

assertThatThrownBy(() -> paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심")))
.isInstanceOf(BadRequestException.class);
Expand All @@ -329,7 +330,7 @@ class PaymentFacadeServiceTest extends BaseTest {
void 결제_취소_시_400_에러_응답_파싱에_실패하면_InternalServerErrorException을_던진다() {
HttpClientErrorException clientError = mock(HttpClientErrorException.class);
when(clientError.getResponseBodyAs(Failure.class)).thenReturn(null);
when(tosspaymentsClient.cancelPayment(any(), any())).thenThrow(clientError);
when(tosspaymentsClient.cancelPayment(any(), any(), any())).thenThrow(clientError);

assertThatThrownBy(() -> paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심")))
.isInstanceOf(InternalServerErrorException.class)
Expand All @@ -338,7 +339,7 @@ class PaymentFacadeServiceTest extends BaseTest {

@Test
void 결제_취소_시_5xx_에러가_발생하면_InternalServerErrorException을_던진다() {
when(tosspaymentsClient.cancelPayment(any(), any()))
when(tosspaymentsClient.cancelPayment(any(), any(), any()))
.thenThrow(new HttpServerErrorException(HttpStatus.INTERNAL_SERVER_ERROR));

assertThatThrownBy(() -> paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심")))
Expand All @@ -348,7 +349,7 @@ class PaymentFacadeServiceTest extends BaseTest {

@Test
void 결제_취소_시_네트워크_에러가_발생하면_InternalServerErrorException을_던진다() {
when(tosspaymentsClient.cancelPayment(any(), any()))
when(tosspaymentsClient.cancelPayment(any(), any(), any()))
.thenThrow(new ResourceAccessException("네트워크 오류"));

assertThatThrownBy(() -> paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심")))
Expand All @@ -358,7 +359,7 @@ class PaymentFacadeServiceTest extends BaseTest {

@Test
void 결제_취소_시_예상치_못한_예외가_발생하면_InternalServerErrorException을_던진다() {
when(tosspaymentsClient.cancelPayment(any(), any()))
when(tosspaymentsClient.cancelPayment(any(), any(), any()))
.thenThrow(new RuntimeException("예상치 못한 오류"));

assertThatThrownBy(() -> paymentFacadeService.cancelPayment(new CancelRequest("payment_key", "단순 변심")))
Expand Down