API 멱등성
이지페이 온라인 결제 API는 클라이언트가 동일한 요청을 반복 전송하더라도 서버에서 중복 처리를 방지하기 위해 멱등성 키(Idempotency Key)를 지원합니다.
클라이언트는 요청 시 데이터 필드(상점 거래고유번호)에 멱등성 키를 포함하여 전송해야 합니다. 멱등성 키는 요청당 고유한 키 값(UUID 또는 랜덤 문자열)이어야 하며, 동일 키로 재요청 시 서버는 중복 요청 오류응답을 반환합니다.
API 요청 시 유니크한 멱등성 키를 생성하여 아래와 같이 요청/응답 데이터(상점 거래고유번호)에 입력합니다. 요청 시 전달한 멱등성 키는 응답 시 그대로 전달 받을 수 있습니다.
요청/응답 Body 예
{
"shopTransactionId": "{Idempotency Key}",
}
멱등성 키(Idempotency Key)
- 멱등성 키(Idempotency Key)는 클라이언트가 직접 생성, 관리해야 하며 요청마다 고유해야 합니다.
- 키 유효 시간은 요청 당일 자정까지 유효하며, 이 기간 내 동일 키 재요청 시 중복 오류가 발생할 수 있습니다.
- 키가 다르면 같은 내용의 요청이라도 다른 요청으로 간주되니 주의해야 합니다.
API 멱등성 키 생성
| 언어 | 추천 함수 |
|---|---|
| Java | UUID.randomUUID |
| Python | uuid (Python 2, Python 3) |
| PHP | uniqid |
| C# | Guid.NewGuid |
| Ruby | SecureRandom.uuid |
| Node.js | uuid |