멱등성

어떤 문제를 줄여주나요?

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

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

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

요청에는 어떻게 넣나요?

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

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

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

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

주문번호와의 차이

주문번호는 주문을 구분하고 멱등키는 한 번 처리하려는 작업을 구분해요. 한 주문에서 여러 번 부분 취소할 수 있으므로 주문번호 하나를 모든 취소 작업의 멱등키로 쓰면 안 돼요.

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

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