결제 취소하기

토스페이먼츠 결제 취소 API로 금액 전액・부분 환불하는 방법, 가상계좌 결제 취소하는 방법, 결제위젯에서 가상계좌 정보 확인하는 방법을 소개합니다.

API 실행해보기

결제 취소 기한

먼저 각 결제수단마다 취소 기한, 취소 소요 시간이 다른데요. 아래 표에서 정보를 확인하고 구매자에게 필요한 정보를 안내해주세요.

결제 수단	취소 기한	취소 소요 기간
카드	취소 기한은 없지만, 카드사 별로 결제 데이터 보관 기간이 달라서 1년을 초과하면 취소가 안될 수 있어요.	결제가 매입되기 전에는 취소 직후 환불됩니다. 매입 이후 또는 부분 취소는 요청 후 영업일 기준 3~4일이 소요됩니다.
계좌이체	180일 이내의 거래만 취소 가능합니다.	실시간으로 환불됩니다.
가상계좌	상점마다 설정이 다를 수 있으나 보통 365일 동안 취소가 가능합니다.	영입일 기준 총 2일이 소요됩니다. 의심거래로 탐지된 결제는 최대 영업일 기준 9일이 소요될 수 있습니다.
휴대폰	통신사 정책으로 결제가 발생한 당월에만 취소가 가능합니다.	당일 취소됩니다.
해외 간편결제(PayPal)	180일 이내의 거래만 취소 가능합니다.	영업일 기준 최대 5일이 소요됩니다. 일부 환불은 카드 회사에 따라 최대 30일이 소요될 수 있습니다.

이미 정산 받은 결제도 취소 가능한가요?

네 가능합니다. 다음 정산금에서 상계처리됩니다.

부분 취소도 가능한가요?

네 가능합니다. 부분 취소를 참고해주세요. 결제 취소 API의 cancelAmount를 부분 취소할 금액으로 설정해주세요. 카드 결제의 부분 취소는 요청 후 영업일 기준 3~4일이 소요됩니다.

하지만 특정 결제수단은 부분 취소가 불가능합니다. 구매자가 가상계좌에 입금을 아직 안 했다면 부분 취소를 할 수 없어요. 발급된 가상계좌의 입금 금액을 바꿀 수 없기 때문이에요. 가상계좌 입금 이후에는 부분 취소가 가능합니다.

에스크로 결제는 어떻게 취소하나요?

배송 정보가 등록되지 않은 에스크로 결제는 다른 결제와 똑같이 취소할 수 있습니다.

하지만 배송 정보가 등록된 에스크로 결제는 구매자가 배송을 받은 뒤에만 결제를 취소할 수 있어요. 구매자가 받는 구매확정 메일에서 '구매취소 요청하기'를 선택하면 됩니다.

만약에 구매자가 배송을 받은 뒤에 부분 취소를 원한다면, 구매확정 메일에서 일단 '구매확정하기'를 선택하고 내 상점에서 결제 취소 API로 부분 취소를 요청하면 됩니다.

전액 취소하기

결제 취소 API 엔드포인트에 결제 승인 API 요청 결과로 받은 paymentKey를 Path 파라미터로 추가하세요. API 요청 본문에 취소 이유를 cancelReason 파라미터로 추가하세요. 멱등키 헤더를 추가하면 중복 취소 없이 안전하게 처리됩니다.

API 응답의 cancels 필드를 확인하세요. 결제 취소 정보 객체가 배열 안에 돌아옵니다. 각 취소 거래마다 거래를 구분하는 transactionKey를 가지고 있습니다.

부분 취소하기

결제 금액 중 일부만 취소하려면 결제 취소 API의 엔드포인트에 paymentKey를 추가하고 cancelAmount 파라미터에 취소할 금액을 추가해주세요. cancelAmount에 값을 넣지 않으면 전액 취소됩니다.

부분 취소를 여러 번 하면 아래와 같이 cancels 필드에 취소 객체가 여러 개 돌아옵니다.

Case 1. 가상계좌 결제 환불하기

가상계좌 결제를 취소하면 취소일+2일에 은행에서 결제 고객의 계좌로 입금 처리를 해줍니다. 따라서 가상계좌 결제를 취소할 때는 환불받을 고객의 계좌 정보를 결제 취소 API 요청에 포함해야 합니다.

구매자가 입금을 완료했으면: refundReceiveAccount에 환불받을 고객의 계좌 정보를 포함해서 결제 취소를 요청하세요. 환불 계좌의 번호와 예금주의 유효성이 확인되면 해당 계좌로 취소 금액이 환불됩니다.
구매자가 입금하기 전이라면: 일반 결제와 똑같이 취소하세요. refundReceiveAccount 파라미터를 추가할 필요 없습니다. 발급된 가상계좌의 입금 금액을 바꿀 수 없기 때문에 부분 취소가 불가능합니다.

응답은 다른 취소 요청과 동일하게 Payment 객체의 cancels로 돌아옵니다.

Case 2. 결제위젯 환불 계좌 확인하기

결제위젯 어드민 > 기능 > 가상계좌 메뉴에서 가상계좌 환불 정보 입력 > 사용함을 선택했다면 구매자가 환불 계좌 정보를 입력하는 UI를 사용할 수 있어요.

환불 계좌 정보는 결제 승인으로 받은 Payment 객체의 virtualAccount.refundReceiveAccount 필드에서 확인할 수 있어요. 다만 해당 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있기 때문에 결제 승인 직후 응답을 저장해주세요. 30분이 지나면 refundReceiveAccount 필드의 값은 null로 내려옵니다.