Version 2
새로 나온토스페이먼츠 결제 취소 API로 금액 전액・부분 환불하는 방법, 가상계좌 결제 취소하는 방법, 결제위젯에서 가상계좌 정보 확인하는 방법을 소개합니다.
먼저 각 결제수단마다 취소 기한, 취소 소요 시간이 다른데요. 아래 표에서 정보를 확인하고 구매자에게 필요한 정보를 안내해주세요.
결제 수단 | 취소 기한 | 취소 소요 기간 |
---|---|---|
카드 | 취소 기한은 없지만, 카드사 별로 결제 데이터 보관 기간이 달라서 1년을 초과하면 취소가 안될 수 있어요. | 결제가 매입되기 전에는 취소 직후 환불됩니다. 매입 이후 또는 부분 취소는 요청 후 영업일 기준 3~4일이 소요됩니다. |
계좌이체 | 180일 이내의 거래만 취소 가능합니다. | 실시간으로 환불됩니다. |
가상계좌 | 상점마다 설정이 다를 수 있으나 보통 365일 동안 취소가 가능합니다. | 영입일 기준 총 2일이 소요됩니다. 의심거래로 탐지된 결제는 최대 영업일 기준 9일이 소요될 수 있습니다. |
휴대폰 | 통신사 정책으로 결제가 발생한 당월에만 취소가 가능합니다. | 당일 취소됩니다. |
해외 간편결제(PayPal) | 180일 이내의 거래만 취소 가능합니다. | 영업일 기준 최대 5일이 소요됩니다. 일부 환불은 카드 회사에 따라 최대 30일이 소요될 수 있습니다. |
네 가능합니다. 다음 정산금에서 상계처리됩니다.
네 가능합니다. 부분 취소를 참고해주세요. 결제 취소 API의 cancelAmount
를 부분 취소할 금액으로 설정해주세요. 카드 결제의 부분 취소는 요청 후 영업일 기준 3~4일이 소요됩니다.
결제 취소 API 엔드포인트에 결제 승인 API 요청 결과로 받은 paymentKey
를 Path 파라미터로 추가하세요.
API 요청 본문에 취소 이유를 cancelReason
파라미터로 추가하세요. 멱등키 헤더를 추가하면 중복 취소 없이 안전하게 처리됩니다.
API 응답의 cancels
필드를 확인하세요. 결제 취소 정보 객체가 배열 안에 돌아옵니다. 각 취소 거래마다 거래를 구분하는 transactionKey
를 가지고 있습니다.
결제 금액 중 일부만 취소하려면 결제 취소 API의 엔드포인트에 paymentKey
를 추가하고 cancelAmount
파라미터에 취소할 금액을 추가해주세요. cancelAmount
에 값을 넣지 않으면 전액 취소됩니다.
부분 취소를 여러 번 하면 아래와 같이 cancels
필드에 취소 객체가 여러 개 돌아옵니다.
가상계좌 결제를 취소하면 취소일+2일에 은행에서 결제 고객의 계좌로 입금 처리를 해줍니다. 따라서 가상계좌 결제를 취소할 때는 환불받을 고객의 계좌 정보를 결제 취소 API 요청에 포함해야 합니다.
- 구매자가 입금을 완료 했으면:
refundReceiveAccount
에 환불받을 고객의 계좌 정보를 포함해서 결제 취소를 요청하세요. 환불 계좌의 번호와 예금주의 유효성이 확인되면 해당 계좌로 취소 금액이 환불됩니다. - 구매자가 입금을 하기 전이라면: 일반 결제와 똑같이 취소하세요.
refundReceiveAccount
파라미터를 추가할 필요 없습니다.
응답은 다른 취소 요청과 동일하게 Payment 객체의 cancels
로 돌아옵니다.
결제위젯 어드민 > 기능 > 가상계좌 메뉴에서 가상계좌 환불 정보 입력 > 사용함을 선택했다면 고객이 환불 계좌 정보를 입력하는 UI를 사용할 수 있어요.
환불 계좌 정보는 결제 승인으로 받은 Payment 객체의 virtualAccount.refundReceiveAccount
필드에서 확인할 수 있어요.
다만 해당 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있기 때문에 결제 승인 직후 응답을 저장해주세요. 30분이 지나면 refundReceiveAccount
필드의 값은 null
로 내려옵니다.
저장한 정보를 결제 취소 API의 파라미터로 사용하세요. 결제위젯에서 고객의 환불 정보를 받는 UI만 제공하기 때문에 환불 계좌 정보를 입력 받아도 해당 계좌로 자동 환불되지 않습니다.