# 멱등성 — Idempotency / Idempotency Key

> 멱등성은 같은 작업을 여러 번 요청해도 한 번 처리한 것과 같은 효과를 내는 성질이에요. 결제 API에서는 멱등키로 같은 작업의 재시도를 구분해요.

- 원문: https://docs.support-b.com/glossary/idempotency
- 분류: 개발·연동
- 함께 찾는 표현: 멱등키, 중복 요청 방지
- 작성: [이성연](https://docs.support-b.com/authors/seongyeon-lee) (대표, 서포트비)
- 검토일: 2026-10-06
- 수정일: 2026-10-13

**적용 범위**: PG가 멱등키를 지원하는 API 기준이에요. 지원하는 API·키 유효기간·오류 재시도 정책은 사업자별로 달라요.

## 어떤 문제를 줄여주나요?

PG가 취소 요청을 처리했지만 네트워크 문제로 가맹점 서버가 응답을 받지 못할 수 있어요. 이때 새 키로 다시 요청하면 별도의 취소로 처리될 위험이 있어요. 멱등키는 PG가 같은 작업의 재시도임을 알아보는 식별값이에요.

## 가상 예시: 부분 취소 요청을 재시도

한 주문에서 1만 원을 부분 취소하는 작업에 키 A를 붙여요. 응답을 받지 못해 같은 작업을 다시 요청할 때는 PG의 지원 정책에 따라 같은 키 A와 같은 요청 내용을 사용해요. 이후 별도로 5천 원을 더 취소하는 작업에는 새 키를 써요.

## 요청에는 어떻게 넣나요?

멱등키를 지원하는 PG는 보통 POST 요청의 헤더에 `Idempotency-Key`를 넣도록 해요. 키는 UUID처럼 무작위로 생성한 고유 값으로 만들어요. 허용 길이와 유효기간은 PG의 API 문서에서 확인해요.

유효기간이 지나면 기존 키로 중복 처리를 막을 수 없어요. 먼저 거래 상태와 작업 기록을 확인한 뒤 추가 처리가 필요한 경우에 새 키로 요청해야 해요. 오류가 났다는 이유만으로 키를 바꿔 같은 작업을 다시 요청하지 않도록 해요.

```http
POST {PG사의 취소 API 경로}
Idempotency-Key: 5f0a8d2e-6b1c-4c7e-9a3d-2e8f1b7c4d90
Content-Type: application/json
```

위 예시는 헤더 형식을 보여주는 가상의 요청이에요. 실제 요청에는 PG가 지정한 경로·인증 정보·본문이 필요하고 키의 유효기간과 길이 제한도 PG마다 달라요.

## 주문번호와의 차이

[주문번호](https://docs.support-b.com/glossary/payment-id)는 주문을 구분하고 멱등키는 한 번 처리하려는 작업을 구분해요. 한 주문에서 여러 번 부분 취소할 수 있으므로 주문번호 하나를 모든 취소 작업의 멱등키로 쓰면 안 돼요.

## 멱등키만 넣으면 항상 안전한가요?

멱등키는 PG가 지원하는 API와 유효기간 안에서 같은 요청을 보낼 때 중복 처리를 막아줘요. 키의 유효기간이 지났거나 요청 내용이 달라졌다면 해당 PG의 처리 규칙을 확인해요. 가맹점 서버에서도 작업 기록을 남기고 중복 출고를 막아야 해요.