결제 취소
이 문서는 카카오페이 결제 취소 방법을 안내합니다.
결제 취소하기
기본 정보
메서드 |
URL |
인증 방식 |
POST |
https://kapi.kakao.com/v1/payment/cancel |
서비스 앱 어드민 키 |
결제 고유번호인 tid
에 해당하는 결제건에 대해 지정한 금액만큼 결제 취소를 요청합니다. 앱 어드민 키를 헤더에 담아 파라미터의 값과 함께 POST
로 요청합니다.
성공 시 응답은 본문에 JSON
객체로 결제 취소 내역을 포함합니다. 실패한 경우에는 카드사 등 결제 수단의 실패 정보가 필요에 따라 포함될 수 있습니다.
요청
헤더
이름 |
설명 |
필수 |
Authorization |
Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
Content-type |
Content-type: application/x-www-form-urlencoded;charset=utf-8 요청 데이터 타입 |
O |
본문
이름 |
타입 |
설명 |
필수 |
cid |
String |
가맹점 코드, 10자 |
O |
cid_secret |
String |
가맹점 코드 인증키, 24자, 숫자+영문 소문자 조합 |
X |
tid |
String |
결제 고유번호 |
O |
cancel_amount |
Integer |
취소 금액 |
O |
cancel_tax_free_amount |
Integer |
취소 비과세 금액 |
O |
cancel_vat_amount |
Integer |
취소 부가세 금액 요청 시 값을 전달하지 않을 경우, (취소 금액 - 취소 비과세 금액)/11, 소숫점이하 반올림 |
X |
cancel_available_amount |
Integer |
취소 가능 금액(결제 취소 요청 금액 포함) |
X |
payload |
String |
해당 요청에 대해 저장하고 싶은 값, 최대 200자 |
X |
응답
본문
이름 |
타입 |
설명 |
aid |
String |
요청 고유 번호 |
tid |
String |
결제 고유 번호, 10자 |
cid |
String |
가맹점 코드, 20자 |
status |
String |
결제 상태 |
partner_order_id |
String |
가맹점 주문번호, 최대 100자 |
partner_user_id |
String |
가맹점 회원 id, 최대 100자 |
payment_method_type |
String |
결제 수단, CARD 또는 MONEY 중 하나 |
amount |
Amount |
결제 금액 정보 |
approved_cancel_amount |
ApprovedCancelAmount |
이번 요청으로 취소된 금액 |
canceled_amount |
CanceledAmount |
누계 취소 금액 |
cancel_available_amount |
CancelAvailableAmount |
남은 취소 가능 금액 |
item_name |
String |
상품 이름, 최대 100자 |
item_code |
String |
상품 코드, 최대 100자 |
quantity |
Integer |
상품 수량 |
created_at |
Datetime |
결제 준비 요청 시각 |
approved_at |
Datetime |
결제 승인 시각 |
canceled_at |
Datetime |
결제 취소 시각 |
payload |
String |
취소 요청 시 전달한 값 |
status(JSON)
이름 |
설명 |
READY |
결제 요청 |
SEND_TMS |
결제 요청 메시지(TMS) 발송 완료 |
OPEN_PAYMENT |
사용자가 카카오페이 결제 화면 진입 |
SELECT_METHOD |
결제 수단 선택, 인증 완료 |
ARS_WAITING |
ARS 인증 진행 중 |
AUTH_PASSWORD |
비밀번호 인증 완료 |
ISSUED_SID |
SID 발급 완료 정기 결제 시 SID만 발급 한 경우 |
SUCCESS_PAYMENT |
결제 완료 |
PART_CANCEL_PAYMENT |
부분 취소 |
CANCEL_PAYMENT |
결제된 금액 모두 취소 부분 취소 여러 번으로 모두 취소된 경우 포함 |
FAIL_AUTH_PASSWORD |
사용자 비밀번호 인증 실패 |
QUIT_PAYMENT |
사용자가 결제 중단 |
FAIL_PAYMENT |
결제 승인 실패 |
amount(JSON)
이름 |
타입 |
설명 |
total |
Integer |
전체 결제 금액 |
tax_free |
Integer |
비과세 금액 |
vat |
Integer |
부가세 금액 |
point |
Integer |
포인트 금액 |
discount |
Integer |
할인 금액 |
green_deposit |
Integer |
컵 보증금 |
approved_cancel_amount(JSON)
이름 |
타입 |
설명 |
total |
Integer |
이번 요청으로 취소된 전체 금액 |
tax_free |
Integer |
이번 요청으로 취소된 비과세 금액 |
vat |
Integer |
이번 요청으로 취소된 부가세 금액 |
point |
Integer |
이번 요청으로 취소된 포인트 금액 |
discount |
Integer |
이번 요청으로 취소된 할인 금액 |
green_deposit |
Integer |
컵 보증금 |
canceled_amount(JSON)
이름 |
타입 |
설명 |
total |
Integer |
취소된 전체 누적 금액 |
tax_free |
Integer |
취소된 비과세 누적 금액 |
vat |
Integer |
취소된 부가세 누적 금액 |
point |
Integer |
취소된 포인트 누적 금액 |
discount |
Integer |
취소된 할인 누적 금액 |
green_deposit |
Integer |
컵 보증금 |
cancel_available_amount(JSON)
이름 |
타입 |
설명 |
total |
Integer |
전체 취소 가능 금액 |
tax_free |
Integer |
취소 가능한 비과세 금액 |
vat |
Integer |
취소 가능한 부가세 금액 |
point |
Integer |
취소 가능한 포인트 금액 |
discount |
Integer |
취소 가능한 할인 금액 |
green_deposit |
Integer |
컵 보증금 |
예제
요청
curl -v -X POST "https://kapi.kakao.com/v1/payment/cancel" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "cid=TC0ONETIME" \
-d "tid=T1234567890123456789" \
-d "cancel_amount=2200" \
-d "cancel_tax_free_amount=0" \
-d "cancel_vat_amount=200" \
-d "cancel_available_amount=4000"
응답: 결제 취소 성공
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"aid": "A5678901234567890123",
"tid": "T1234567890123456789",
"cid": "TC0ONETIME",
"status": "CANCEL_PAYMENT",
"partner_order_id": "partner_order_id",
"partner_user_id": "partner_user_id",
"payment_method_type": "MONEY",
"item_name": "초코파이",
"quantity": 1,
"amount": {
"total": 2200,
"tax_free": 0,
"vat": 200,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"approved_cancel_amount": {
"total": 2200,
"tax_free": 0,
"vat": 200,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"canceled_amount": {
"total": 2200,
"tax_free": 0,
"vat": 200,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"cancel_available_amount": {
"total": 0,
"tax_free": 0,
"vat": 0,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"created_at": "2016-11-15T21:18:22",
"approved_at": "2016-11-15T21:20:48",
"canceled_at": "2016-11-15T21:28:28"
}
응답: 결제 취소 실패
HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
"code": -781,
"msg": "cancel failure!",
"extras": {
"method_result_code": "6666",
"method_result_message": "원거래없음"
}
}
더 보기