결제 환불
결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
요청 파라미터
가맹점 API Key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
토스페이 토큰
환불 번호
미입력 시 자동 생성되며 환불 완료 응답에서 확인 가능합니다. 매회 요청마다 유니크한 값을 사용하시길 권장드립니다.
refundNo를 활용하면 중복 환불요청을 방지할 수 있고, 네트워크나 기타의 이유로 처리 응답을 수신하지 못한 경우 재활용할
수 있습니다.
멱등성 적용 여부
true: 사용 (기본값), false: 미사용
멱등성 적용을 원하시는 경우 true, 미사용의 경우 false로 선언해 주시기 바랍니다.
미입력 시 기본값으로 멱등성이 활성화되어, 동일한 요청을 반복적으로 수행하더라도 동일한 결과인 성공으로 응답("code": 0) 처리됩니다.
환불 사유
환불 사유는 한글 및 숫자, 영문자, 특수문자 _ - : . ^ @ ( ) [ ] # / ! % ? & 만 허용합니다.
환불할 금액
미입력 시 환불할 결제건의 남은 전액을 환불 처리하며, 부분환불 시 필수로 amount를 활용해주세요.
만일 즉시할인이 적용된 거래의 부분환불이 필요한 경우, 가맹점에서는 환불이 필요한 총 요청 금액만 전달해 주시면 됩니다. 계산은 토스페이 서버에서 자동으로 처리합니다.
환불할 금액 중 비과세금액
환불할 금액 중 비과세 금액, 없으면 0으로 설정합니다.
환불할 금액 중 과세금액
환불할 금액 중 부가세
값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
환불할 금액 중 봉사료
결제 생성 시 봉사료 설정한 경우에만 입력 가능
Example Request
curl "https://pay.toss.im/api/v2/refunds" \
-H "Content-Type: application/json" \
-d '{
"payToken":"example-payToken",
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq"
}'응답 파라미터
응답코드
| 값 | 설명 |
|---|---|
| 0 | 성공 |
| -1 | 실패 (실패사유는 msg와 errorCode로 제공) |
환불 번호
환불요청 시 가맹점이 전달한 refundNo로 리턴됩니다. 미입력 시, 서버에서 자동 생성하며 transactionId 값과 동일한
value 값을 리턴합니다.
환불 가능 금액
환불 성공 후 남은 환불 가능 금액
할인된 금액
환불 성공 후 남은 할인적용 금액이 전달되고, 전액 환불이거나 할인 적용이 안되었다면 0을 리턴합니다.
예를 들어, 10% 할인을 받아 10,000원 결제를 9,000원에 결제했고, 4,000원을 부분 환불하면 최종적으로 6,000원 결제의 600원
할인을 받은 것이 되므로 discountedAmount 값은 600원으로 리턴됩니다.
가맹점 측에서는 환불요청 금액만 전달해 주시면 되고, 토스페이 서버에서 자동으로 우선순위를 지정하여 할인금액을 차감합니다.
지불수단 승인금액
환불 성공 후 남은 지불수단의 승인금액
환불요청 금액
가맹점에서 환불 요청 시 전달한 amount 금액
환불요청 금액 중 실 차감된 할인 금액
환불요청 시 전달한 amount 금액 중 토스 서버에서 자동 차감된 할인 금액으로 차감액이 없으면 0으로 리턴됩니다.
할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.
환불요청 금액 중 실 차감된 지불수단 금액
환불요청 시 전달한 amount 금액 중 토스 서버에서 자동 차감된 지불수단 금액으로 차감액이 없으면 0으로 리턴됩니다.
결제건의 환불 처리 시간
결제건의 환불 처리 시간 (yyyy-MM-dd HH:mm:ss)
현금영수증 관리번호 식별값
국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별 값입니다.
해당 필드 존재로 현금영수증 발급 구분 가능합니다.
환불된 결제토큰
거래 트랜잭션 아이디
환불된 거래건의 매출전표 확인을 위하여 필요한 옵션 값이므로 가맹점의 관리가 필요합니다.
카드 타입
승인된 카드의 타입을 구분할 수 있습니다.
| 값 | 설명 |
|---|---|
| CREDIT | 신용카드 |
| CHECK | 체크카드 |
| PREPAYMENT | 선불카드 |
마스킹된 카드번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
카드 사용자 구분
| 값 | 설명 |
|---|---|
| PERSONAL | 본인 카드 |
| PERSONAL_FAMILY | 가족 카드 |
| CORP_PERSONAL | 법인지정 결제계좌 임직원 |
| CORP_PRIVATE | 법인 공용 |
| CORP_COMPANY | 법인지정 결제계좌 회사(하나카드만) |
카드 BIN 넘버
카드사에서 준 카드 BIN 번호(마스킹되어 있을 수 있습니다). 100% 신뢰는 불가합니다.
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드번호 끝 4자리를 전달합니다. (카드사에 따라 마스킹이 포함되어
있을 수 있습니다)
신용카드 매출전표 호출 URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL
은행 코드
사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.
은행 명
계좌번호
계좌번호는 일부 마스킹을 포함하고 있습니다.
응답이 성공이 아닌 경우 설명 메세지
에러 코드
| 값 | 설명 |
|---|---|
| INACTIVE_USER | 탈퇴한 사용자입니다. 환불이 불가능합니다. |
| COMMON_REFUND_ERROR | 환불이 불가능한 상태입니다. |
| REFUND_EXCEED_DAILY | 환불 금액이 상점의 일일 환불 한도보다 클 수 없습니다. |
| 그 외의 에러 코드 |
Example Response
{
"code": 0,
"refundNo": "3243c76e-e9cf-4669-881b-33a3b82ddf49",
"approvalTime": "2020-04-29 11:32:52",
"cashReceiptMgtKey": "0123456-abcd-9abcd0Df",
"refundableAmount": 2000,
"discountedAmount": 0,
"paidAmount": 1000,
"refundedAmount": -2000,
"refundedDiscountAmount": 0,
"refundedPaidAmount": -2000,
"payToken": "example-payToken",
"transactionId": "3243c76e-e9cf-4669-881b-33a3b82ddf49",
"cardMethodType": "CREDIT",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cardNum4Print": "1234",
"cardBinNumber": "654321"
// payMethod 가 TOSS_MONEY 일때
//"cashReceiptMgtKey": "0123456-abcd-9abcd0Df",
//"accountBankCode" : "88",
//"accountBankName" : "신한은행",
//"accountNumber" : "110******676"
}