결제 서버연동breadcrumb취소

결제 취소 API 연동 가이드

결제가 승인된 이후, 환불이나 결제 취소가 필요한 경우 결제 취소 API를 사용해요.
결제 승인 응답으로 받은 transactionId를 기반으로 전체 또는 부분 금액을 취소할 수 있어요.

결제 취소 흐름은 아래와 같아요.

결제 서버 인증은 어떻게 하나요?
API 연동에 반드시 필요한 결제서버 인증 방식에 대해 궁금하다면,
결제서버 인증 가이드를 먼저 참고해주세요.


결제 취소 API란?

결제 취소 API는 사용자가 결제 완료 후 환불을 요청했거나, 가맹점이 취소했을 때 사용해요

API 정보

항목값
HTTP MethodPOST
Endpointhttps://one-api.danalpay.com/payments/cancel
인증 방식Basic Auth
요청 Formatapplication/json
응답 Formatapplication/json

요청 파라미터

파라미터타입필수길이설명
methodStringO사용자가 인증을 완료한 결제수단입니다.
결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 결제수단이 전달됩니다.
  • 휴대폰 : MOBILE
  • 카드 : CARD
  • 계좌이체 : TRANSFER
  • 가상계좌 : VACCOUNT
  • 컬쳐랜드상품권 : CULTURELAND
  • 도서문화상품권 : BOOK_AND_LIFE

거래번호와 결제수단이 일치하지 않으면 취소에 실패합니다.
amountStringO9자취소 요청 금액입니다.
merchantIdStringO10자상점 아이디(계약 시 발급 받은 CPID를 입력해주세요.)
transactionIdStringO32자
취소 할 다날 거래ID입니다.
[도서문화,컬쳐랜드] 결제 승인 요청(Confirm)시 전달받은 Res TransactionId 를 전달하여,
취소(Cancel) Req TransactionId 로 사용해야 해요.
cancelTypeString1자취소 타입입니다.
  • 전체취소 : C
  • 부분취소 : P
미 입력 시 default는 전체취소(C) 입니다.
cancelRequesterString20자취소 요청자 입니다. - 시스템 취소, 사용자 취소 등을 구분하기 위해 사용합니다.
cancelReasonString255자취소사유
*cancelType을 입력하지 않으면 기본적으로 전체 취소(C)로 처리됩니다.

응답 파라미터

파라미터타입설명
codeString취소 요청 결과 응답 코드 (예: SUCCESS — 결제 성공, 실패 시 에러 코드 제공)
messageString취소 요청 결과 응답 메시지입니다. 실패 시 가맹점 창에서 메시지를 노출 할 수 있습니다.
transactionIdString취소 거래ID입니다. 요청한 거래ID와 다른 의미로, 요청한 거래ID를 취소한 거래의 ID입니다.
*응답 code가 SUCCESS가 아닌 경우, message 값을 사용자 또는 관리자 화면에 출력할 수 있어요.

요청 예시

curl -X POST \
<https://one-api.danalpay.com/payments/confirm> \
-H "Authorization: Basic dGVzdF9jbGllbnRfa2V5Og==" \
-H "Content-Type: application/json" \
-d '{
      "method": "CARD",
      "transactionId": "202404290001234567890",
      "merchantId": "M123456",
      "amount": "10000",
      "orderId": "ORDER-20240429-0001"
    }'

응답 예시

{
"code": "SUCCESS",
"message": "결제가 정상적으로 완료되었습니다.",
"transactionId": "202404290001234567890",
"orderId": "ORDER-20240429-0001"
}

주의사항

  • 취소 요청 시 amount는 원거래 금액 이내여야 합니다.
  • cancelType 미입력 시 전체취소(C)가 기본값입니다.
  • 가상계좌 취소 시 채번된 계좌가 반납되어 더 이상 입금이 불가능해집니다.
맨 위로