결제 취소 API

해당 페이지는 NHN KCP 결제 취소 요청 및 응답에 대해 설명합니다.
결제 취소 API는 승인된 결제 건에 대해 전체 취소 또는 부분 취소를 처리하는 API입니다.
취소 요청 시 보안을 위해 site_cd, tno, mod_type 조합으로 생성한 서명데이터를 함께 전송하세요.

결제 승인 완료

Option결제 취소

요약

HTTP Method

POST 방식으로 JSON Body를 전송합니다.

Content-Type

application/json; charset=utf-8 형식으로 요청합니다.

통신 보안

TLS 1.2 이상 환경에서 통신합니다.

테스트 URL

https://stg-spl.kcp.co.kr/gw/mod/v1/cancel

운영 URL

https://spl.kcp.co.kr/gw/mod/v1/cancel

정상 응답 기준

res_cd 값이 0000이면 정상 처리입니다.

요청 정보

전체 취소 Request Body 예시

{
	"site_cd": "T0000",
	"tno": "20250521435727",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"kcp_sign_data": "XILKM7AibjMT...t1fg2LAajA==",
	"mod_type": "STSC",
	"mod_desc": "단순변심",
	"mod_ip": "0.0.0.1"
}

부분 취소 Request Body 예시

{
	"site_cd": "T0000",
	"tno": "20250521435727",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"kcp_sign_data": "XILKM7AibjMT...t1fg2LAajA==",
	"mod_type": "STPC",
	"mod_mny": "3000",
	"rem_mny": "10000",
	"mod_desc": "단순변심",
	"mod_ip": "0.0.0.1"
}

취소 유형별 요청 차이

전체 취소

mod_type에 STSC를 사용합니다. 승인된 거래 건 전체 금액을 취소합니다.

부분 취소

mod_type에 STPC를 사용하며, mod_mny와 rem_mny를 함께 전송합니다.

복합과세 부분 취소

복합과세 거래를 부분 취소할 때는 공급가액·부가세·비과세 금액을 함께 전송합니다.

요청 파라미터

site_cd필수string5

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.ex) site_cd: T0000

tno필수string14

승인 완료 시 발급되는 NHN KCP 거래번호입니다. 취소 대상 거래를 식별하므로 가맹점에서 저장·관리해야 합니다.ex) tno: 20250521435727

kcp_cert_info필수string가변

NHN KCP에서 발급하는 서비스 인증서입니다.
파트너관리자 인증센터에서 다운로드한 PEM 파일 내용을 직렬화하여 사용합니다.ex) kcp_cert_info: -----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

kcp_sign_data필수string가변

가맹점의 부인방지와 요청 데이터의 무결성 검증을 위한 서명데이터입니다.
site_cd + "^" + tno + "^" + mod_type 규칙으로 문자열을 생성한 뒤, 개인키를 사용하여 SHA256withRSA 방식으로 서명합니다.ex) kcp_sign_data: XILKM7AibjMT...t1fg2LAajA==

mod_type필수string4

취소 유형입니다. 전체 취소는 STSC, 부분 취소는 STPC를 사용합니다.ex) 전체 취소, mod_type: STSC
ex) 부분 취소, mod_type: STPC

mod_mnynumber12

부분취소 요청 금액입니다. mod_type이 STPC일 때 필수로 전송합니다.
복합과세 부분취소 시 mod_tax_mny + mod_vat_mny + mod_free_mny 합계가 mod_mny와 일치해야 합니다.ex) mod_mny: 3000

rem_mnynumber12

부분취소 가능 금액입니다. 현재 거래 건에 남아있는 금액을 입력하며, mod_type이 STPC일 때 필수로 전송합니다.ex) rem_mny: 10000

mod_descstring256

결제 취소 사유입니다.ex) mod_desc: 단순변심

mod_ipstring15

결제 취소 요청자 IP입니다.ex) mod_ip: 0.0.0.1

mod_tax_mnynumber12

부분취소 요청 금액 중 공급가액에 해당하는 금액입니다.ex) mod_tax_mny: 363

mod_vat_mnynumber12

부분취소 요청 금액 중 부가가치세에 해당하는 금액입니다.
부가가치세는 mod_mny의 10%입니다.ex) mod_vat_mny: 37

mod_free_mnynumber12

부분취소 요청 금액 중 비과세 금액입니다.ex) mod_free_mny: 0

응답 정보

정상 처리 시 res_cd 값으로 0000이 리턴됩니다. 부분취소인 경우 부분취소 금액, 잔액, 부분취소 고유번호가 함께 리턴될 수 있습니다.

전체 취소 Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"res_en_msg": "processing completed",
	"tno": "20250521435727",
	"canc_time": "20260310145324"
}

부분 취소 Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"res_en_msg": "processing completed",
	"tno": "20250521435727",
	"mod_mny": "500",
	"rem_mny": "504",
	"mod_pcan_seq_no": "24071031943029",
	"canc_time": "20260310145324",
	"card_mod_mny": "500",
	"coupon_mod_mny": "0"
}

응답 파라미터

res_cdstring4

결과 코드입니다. 정상 처리된 경우 0000을 리턴합니다.ex) res_cd: 0000

res_msgstring100

결과 메시지입니다.ex) res_msg: 정상처리

res_en_msgstring100

영문 결과 메시지입니다.ex) res_en_msg: processing completed

tnostring14

취소 요청한 거래번호입니다.ex) tno: 20250521435727

canc_timestring14

취소 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) canc_time: 20260310145324

mod_mnynumber12

부분취소 완료 금액입니다.ex) mod_mny: 500

rem_mnynumber12

부분취소 후 남은 금액입니다.ex) rem_mny: 504

mod_pcan_seq_nostring14

부분취소 고유번호입니다. 부분취소 시마다 다른 값이 응답되며, 부분취소 시퀀스 관리에 사용할 수 있습니다.ex) mod_pcan_seq_no: 24071031943029

card_mod_mnynumber12

카드 부분취소 금액입니다. 쿠폰을 사용한 거래의 경우 쿠폰 조건에 따라 카드와 쿠폰 취소 금액이 각각 리턴됩니다.ex) card_mod_mny: 500

coupon_mod_mnynumber12

쿠폰 취소 금액입니다.ex) coupon_mod_mny: 0

구현 참고사항

JSP 샘플은 API 스펙 확인 후 실제 구현 흐름을 참고할 때 확인하세요.

JSP 샘플 구현 포인트 보기

JSP 샘플에서는 site_cd + "^" + tno + "^" + mod_type 조합으로 서명데이터를 생성한 뒤, 취소 API에 JSON Body로 전송합니다. 부분취소일 때만 mod_mny, rem_mny를 추가합니다.

// 결제 취소 API URL
String target_URL = "https://stg-spl.kcp.co.kr/gw/mod/v1/cancel";

// 취소 정보
String mod_type = "STSC"; // 전체취소: STSC, 부분취소: STPC
String mod_ip = "0.0.0.1";
String tno = "";
String mod_desc = "";
String mod_mny = "";
String rem_mny = "";

// 서명데이터 생성
String cancel_target_data = site_cd + "^" + tno + "^" + mod_type;
String kcp_sign_data = makeSignatureData(cancel_target_data);

// 요청 JSON 구성
json_req.put("kcp_cert_info", kcp_cert_info);
json_req.put("site_cd", site_cd);
json_req.put("mod_type", mod_type);
json_req.put("mod_ip", mod_ip);
json_req.put("tno", tno);
json_req.put("mod_desc", mod_desc);
json_req.put("kcp_sign_data", kcp_sign_data);

// 부분취소 시 필수
if (mod_type.equals("STPC")) {
  json_req.put("mod_mny", mod_mny);
  json_req.put("rem_mny", rem_mny);
}

// API 요청 Header
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept-Charset", "UTF-8");

// 정상 응답이면 res_cd 값이 0000
if ("0000".equals(res_cd)) {
  // tno, canc_time, 부분취소 응답값 등을 저장
}