가상계좌 사용중지 API

해당 페이지는 NHN KCP 가상계좌 사용중지 요청 및 응답에 대해 설명합니다.
가상계좌 사용중지는 발급된 가상계좌에 더 이상 입금할 수 없도록 처리하는 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": "20260715435727",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"kcp_sign_data": "XILKM7AibjMT...t1fg2LAajA==",
	"mod_type": "STSC",
	"mod_desc": "단순변심",
	"mod_ip": "0.0.0.1"
}

요청 파라미터

site_cd필수 string5

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

tno필수 string14

NHN KCP 거래번호입니다. 입금 통보 확인, 사용중지, 매출전표 등 후속 처리에 사용하므로 반드시 저장합니다.ex) tno: 20260715435727

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 서명한 후 Base64로 인코딩하여 생성합니다.ex) kcp_sign_data: XILKM7AibjMT...t1fg2LAajA==

mod_type필수 string4

변경 타입입니다. 가상계좌 사용중지 요청에서는 STSC 고정값을 사용하며 임의로 변경할 수 없습니다.ex) mod_type: STSC

mod_desc string256

가상계좌 사용중지 사유입니다.ex) mod_desc: 단순변심

mod_ip string15

가상계좌 사용중지를 요청한 사용자 또는 가맹점 서버의 IP 주소입니다.ex) mod_ip: 0.0.0.1

응답 정보

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리-테스트거래입니다.",
	"res_en_msg": "processing completed",
	"tno": "20260715435727"
}

응답 파라미터

res_cd string4

응답 코드입니다. 정상 처리 시 0000을 리턴합니다.ex) res_cd: 0000

res_msg string100

결과 메시지입니다.ex) res_msg: 정상처리-테스트거래입니다.

res_en_msg string100

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

tno string14

NHN KCP 거래번호입니다. 사용중지를 요청한 거래번호를 그대로 리턴합니다.ex) tno: 20260715435727

구현 참고사항

첨부한 JSP 샘플의 개인키 로딩, 서명데이터 생성 및 사용중지 API 호출 방식을 기준으로 작성했습니다.

JSP 샘플 구현 포인트 보기

서명 대상 문자열은 site_cd + "^" + tno + "^" + mod_type 순서로 생성해야 합니다. 필드 순서나 구분자를 임의로 변경하지 마세요.

// 사용중지 요청값
String site_cd  = "T0000";
String tno      = "20260715435727";
String mod_type = "STSC";
String mod_desc = "단순변심";
String mod_ip   = "0.0.0.1";

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

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

// SHA256WithRSA 서명 후 Base64 인코딩
public static String makeSignatureData(String targetData) throws Exception {
    PrivateKey privateKey = loadSplMctPrivateKeyPKCS8();

    Signature signature = Signature.getInstance("SHA256WithRSA");
    signature.initSign(privateKey);
    signature.update(targetData.getBytes(StandardCharsets.UTF_8));

    return Base64.getEncoder().encodeToString(signature.sign());
}