멱등키

멱등키를 사용하면 민감한 API 요청이 반복적으로 일어나는 문제를 막을 수 있고, 네트워크 이슈나 타임아웃 문제로 응답을 받지 못했을 때도 안전하게 같은 요청을 다시 보낼 수 있습니다. 멱등성의 개념과 구현 방법은 토스페이먼츠 블로그 포스트에서 더 자세히 살펴보세요.

이 페이지에서는 멱등키를 사용해서 안전하게 API 요청을 보내는 방법을 알아봅니다.

멱등성은 연산을 여러 번 하더라도 결과가 달라지지 않는 성질을 뜻합니다. API 요청에서 멱등성을 보장하면 같은 요청이 여러 번 일어나도 항상 첫 번째 요청과 같은 결과가 돌아옵니다.

예를 들어 결제 고객이 부분 취소 요청을 했는데 네트워크가 불안정해서 성공 응답이 전송되지 않을 수 있습니다. 결제 고객은 부분 취소가 이루어지지 않았다고 판단하고 다시 요청을 보내서 두 번 취소되는 문제가 생깁니다. 이런 상황에서 멱등키를 사용하면 같은 요청이 여러 번 처리되지 않아 안전합니다.

결제 취소나 서브몰에 돈을 지급하는 지급대행처럼 같은 요청을 반복해서 보냈을 때 문제가 생길 수 있는 민감한 API는 멱등키를 추가해서 요청하면 안전합니다.

요청 헤더에 Idempotency-Key를 추가하면 멱등한 요청을 보낼 수 있습니다.

Idempotency-Key: {IDEMPOTENCY_KEY}

• 멱등키는 UUID v4와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 최대 길이는 300자입니다.

• 멱등키는 처음 요청에 사용한 날부터 15일 간 유효합니다. 처음 요청한 날부터 15일이 지났다면 새로운 멱등키로 요청하세요.

아래와 같이 API 요청에 멱등키 헤더를 사용하면 같은 요청이 두 번 일어나도 실제로 요청이 이루어지지 않고 첫 번째 요청 응답과 같은 응답을 보내줍니다.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/key-in
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: SAAABPQbcqjEXiDL' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"박토스","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerIdentityNumber":"881212"}'

• 토스페이먼츠 서버는 상점에서 API 요청 헤더로 보낸 멱등키와 API 키, API 주소, HTTP 메서드 조합이 같은 요청이 있는지 확인해서 멱등성을 보장합니다. 따라서 API 키, API 주소, HTTP 메서드가 다르다면 같은 멱등키를 사용해도 괜찮습니다.

멱등키 헤더를 사용할 때 발생할 수 있는 에러는 두 가지가 있습니다. 멱등키 길이가 300자보다 길면 HTTP 400 - INVALID_IDEMPOTENCY_KEY가 돌아옵니다. 300자 이하로 멱등키를 다시 만들어주세요. 첫 번째 요청이 처리중일 때 같은 요청을 다시 보내면 HTTP 409 - IDEMPOTENT_REQUEST_PROCESSING 에러가 돌아옵니다. 이 에러가 돌아오면 다시 한 번 요청해서 응답을 확인하세요.