결제 API 멱등성과 중복 거래 처리

그림으로 이해하기

개념 설명용 도표 · 실제 거래나 운영 화면이 아닙니다.

두 경로 모두 서버 처리가 일어날 수 있습니다. 응답을 못 받았다고 키를 새로 만들지 않습니다.

재시도가 필요한 이유

서버가 거래를 처리했지만 응답이 네트워크에서 사라질 수 있습니다. 클라이언트의 시간 초과만으로 서버가 처리하지 않았다고 판단할 수 없습니다. 새 식별자로 같은 결제를 다시 보내면 중복 데이터가 생길 수 있습니다.

멱등성은 같은 작업을 반복해도 의도한 효과가 반복 증가하지 않도록 설계하는 성질입니다. HTTP POST 자체가 자동으로 이를 보장하지는 않습니다. MDN 멱등성 설명을 참고하고 실제 API의 키 정책을 따르세요.

GUARDIAN에서는 멱등성 계약에 따라 Idempotency-Key를 사용합니다. 재시도 시에는 키뿐 아니라 원본 요청 본문도 보존하세요. 같은 키로 금액을 수정해 보내는 것은 같은 요청의 재시도가 아닙니다.

주문 A의 승인 요청을 보낸 뒤 시간 초과가 발생했다면 새 주문으로 만들지 않습니다. 저장한 원 요청과 키로 재시도하고 이벤트 조회가 가능하면 상태를 확인합니다. 취소는 승인과 다른 업무이므로 해당 취소의 식별 체계를 별도로 유지합니다.

409 같은 충돌 응답을 무조건 반복 요청하면 해결되지 않습니다. 기존 키와 본문, 거래 식별자를 비교해 원인을 정리하세요. 키의 보존 기간이나 중복 판정 범위는 서버 계약에 의존하므로 영구적인 중복 방지를 가정하지 않습니다.

가상 요청 K1의 금액 10000을 보낸 뒤 응답이 유실되면 K1과 원 본문으로 재시도합니다. 금액을 20000으로 바꾼 K1 요청은 재시도가 아니므로 충돌 여부를 확인하고 원인을 수정합니다.

이 사례는 실측 성능이나 실제 고객 자료가 아닙니다. 제품의 적용 범위는 GUARDIAN 공개 API 계약를 기준으로 확인합니다.

응답이 유실되어도 서버는 거래를 처리했을 수 있습니다. GUARDIAN 재시도에는 원본 본문과 멱등 키를 유지하고, 같은 키로 다른 금액을 보내 충돌이 나면 내용을 대조해야 합니다. POST 자체가 중복 방지를 보장하지 않습니다. [GUARDIAN 공개 API 계약] [HTTP 멱등성]
가상 요청 K1의 금액 10000을 보낸 뒤 응답이 유실되면 K1과 원 본문으로 재시도합니다. 금액을 20000으로 바꾼 K1 요청은 재시도가 아니므로 충돌 여부를 확인하고 원인을 수정합니다. (가상 예시) [이 문서의 가상 검증 사례]