부분환불 요청 시 중복 처리 방지 관련 문의
안녕하세요.
저희는 귀사의 결제모듈을 사용하는 홈페이지를 운영 중입니다.
최근 부분환불 처리 과정에서 중복 환불이 발생하는 장애가 있어 문의드립니다.
[장애 발생 개요]
사용자가 부분환불 요청을 1회만 수행했음에도 불구하고, 환불 요청이 0.0005초 간격으로 2회 전송되어, 실제로 부분환불이 두 번 이루어진 상황이 발생했습니다.
원인 분석 결과, WAS 서버 1회, 캐시 서버 1회로 총 두 번 환불 요청이 처리되었습니다.
이로 인해 동일한 거래에 대해 이중 환불이 발생하여 정산에 문제가 생겼습니다.
[현재 운영 환경]
웹 서버 구조: WAS 서버 + 캐시 서버 병행 사용
부분환불 요청은 서버 사이드에서 API 호출로 이루어짐
동일 요청이 병렬 혹은 중복으로 발생할 가능성 있음
[문의사항]
토스페이먼츠 API에서 동일 거래에 대한 중복 환불 요청을 자동으로 차단하는 기능이 있는지 확인 부탁드립니다.
중복 처리를 방지할 수 있는 권장 구현 방식이나 가이드가 있다면 공유 부탁드립니다.
요청 중복에 대한 재처리 방지 키(idempotency key)나 고유 요청 ID를 지정하는 방식이 API에서 지원되는지 확인 부탁드립니다.
향후 동일 문제가 재발하지 않도록 조치가 필요한 상황이므로,
토스페이먼츠 측의 기술적 대응 방안 또는 우회 가능한 구현 가이드를 꼭 부탁드립니다.
감사합니다.
7 Replies
⏳ 잠시만 기다려주세요! 곧 답변드리겠습니다
오류 문의일 경우 아래 정보를 미리 전달해주시면, 빠른 답변에 도움이 됩니다.
- 주문번호(orderId) :
- 문의 내용 :
(img를 함께 첨부해주시면 도움이됩니다)
* 계약관련 내용은 1544-7772로 문의주세요.
* 주말/공휴일에는 답변이 늦을 수 있어요.
요청 중복에 대한 재처리 방지 키(idempotency key) 를 지원하고 있습니다.
인증 및 기타 헤더 설정 | 토스페이먼츠 개발자센터
토스페이먼츠 API를 사용하기 위해 필요한 인증과 헤더 설정 방법입니다.
현재 구모듈인 xpay를 사용중인데 멱등식을 사용가능한가요?
XPAY는 멱등키 지원 안될겁니다.
XPay는 LGD_PCANCELCNT 파라미터를 활용하실 수 있습니다.
- 취소 api 문서: https://docs.google.com/document/d/1NJK2LNYVNV03aMvE3jVXwacKjXh-ZC3kI73WFmugwwQ/edit?tab=t.0
LGD_PCANCELCNT
부분환불요청횟수 (예: 001, 002)
(부분취소환불 요청 시, 중복요청에 의한 환불을 방지하기 위해 가맹점에서 요청횟수를 컨트롤 할 경우에 사용)
※ 반드시 세 자리로만 사용해야 함.
** 카드, 계좌이체, 가상계좌 거래건만 사용 가능
Google Docs
XPAY[API]취소,부분취소_v.1.0.5
Xpay-API-취소,부분취소 Protocol and Core Function Specification Version 1.0.5 2025.03 목차 XPay 연동 샘플 파일 구조 3 XPay 취소 서비스 파라미터 3 ▪ 전체취소 요청 파라미터 3 ▪ 전체취소 응답 파라미터 4 ▪ 부분취소 요청 파라미터 4 ▪ 부분취소 응답 파라미터 5 취...
❤️ 기술문의 경험이 어떠셨나요?!
간단히 코멘트 남겨주세요! 제품 발전에 큰 힘이 됩니다.