결제 서버연동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

transactionId(거래번호)와 method(결제수단)이 일치하지 않으면 취소에 실패합니다.
transactionIdStringO32 byte다날에서 부여한 거래번호를 입력합니다.
사용자 인증이 완료된 거래에 대해 결제 승인 및 취소 처리를 위해 사용되는 고유값으로
결제창에서 인증 완료 시 가맹점 성공 URL로 전달됩니다.
전달된 거래번호로 결제를 발생시키며, 다날과 함께 거래 관리를 위해 가맹점에서 저장해 두시는 것을 권장합니다.
amountStringO결제수단별 상이
취소 금액을 입력합니다.
SDK 호출시 입력한 금액을 넣어주세요.
앞서 안내한바와 같이 결제 수단마다 최소 및 최대 결제 가능 금액이 다르며,
입력한 금액이 해당 수단의 최소 금액 기준에 미달할 경우, 해당 결제 수단은 결제창에 노출되지 않습니다.
merchantIdStringO20 byte계약 완료 후 발급 받은 CPID를 입력합니다.
다날 결제창, ONE API 결제 연동 시 사용되는 ID입니다.
cancelTypeString1 byte취소 타입을 입력합니다. (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": "9810030930",
      "amount": "10000",
      "orderId": "ORDER-20240429-0001"
    }'

응답 예시

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

주의사항

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

← 이전 단계로 이동

맨 위로