페이지 이동경로
  • 문서>
  • 카카오페이>
  • 결제 취소

카카오페이

결제 취소

이 문서는 카카오페이 결제 취소 방법을 안내합니다.

결제 고유번호인 tid에 해당하는 결제건에 대해 지정한 금액만큼 결제 취소를 요청합니다. 앱 어드민 키를 헤더에 담아 파라미터의 값과 함께 POST로 요청합니다.

성공 시 응답은 바디에 JSON 객체로 결제 취소 내역을 포함합니다. 실패한 경우에는 카드사 등 결제 수단의 실패 정보가 필요에 따라 포함될 수 있습니다.

승인 시 컵 보증금 필드(green_deposit)가 존재하는 경우 부분취소가 불가하며, 전체취소만 가능합니다.

Request

URL
POST /v1/payment/cancel HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
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

Response

Name Type Description
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)
Name Description
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)
Name Type Description
total Integer 전체 결제 금액
tax_free Integer 비과세 금액
vat Integer 부가세 금액
point Integer 포인트 금액
discount Integer 할인 금액
green_deposit Integer 컵 보증금
approved_cancel_amount(JSON)
Name Type Description
total Integer 이번 요청으로 취소된 전체 금액
tax_free Integer 이번 요청으로 취소된 비과세 금액
vat Integer 이번 요청으로 취소된 부가세 금액
point Integer 이번 요청으로 취소된 포인트 금액
discount Integer 이번 요청으로 취소된 할인 금액
green_deposit Integer 컵 보증금
canceled_amount(JSON)
Name Type Description
total Integer 취소된 전체 누적 금액
tax_free Integer 취소된 비과세 누적 금액
vat Integer 취소된 부가세 누적 금액
point Integer 취소된 포인트 누적 금액
discount Integer 취소된 할인 누적 금액
green_deposit Integer 컵 보증금
cancel_available_amount(JSON)
Name Type Description
total Integer 전체 취소 가능 금액
tax_free Integer 취소 가능한 비과세 금액
vat Integer 취소 가능한 부가세 금액
point Integer 취소 가능한 포인트 금액
discount Integer 취소 가능한 할인 금액
green_deposit Integer 컵 보증금

Sample

Request
curl -v -X POST "https://kapi.kakao.com/v1/payment/cancel" \
-H "Authorization: KakaoAK ${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"
Response: 결제 취소 성공
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"
}
Response: 결제 취소 실패
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": "원거래없음"
    }
}

더보기