거래 조회 API

해당 페이지는 NHN KCP 거래 조회 요청 및 응답에 대해 설명합니다.
거래 조회 API는 거래 건의 상태와 결제 정보를 확인할 수 있는 조회성 API입니다.
가맹점 DB 처리 실패와 같이 거래 건의 상태 확인이 필요한 경우, 거래조회 API를 통해 현재 거래 상태를 확인할 수 있습니다.
거래번호(tno)로 조회하거나, 거래번호를 알 수 없는 경우 주문번호(mod_ordr_idxx)와 결제일자로 설정한 거래번호(tno)로 조회할 수 있습니다.

결제 승인 완료

Option거래 조회

요약

HTTP Method

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

Content-Type

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

통신 보안

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

테스트 URL

https://stg-spl.kcp.co.kr/std/inquery

운영 URL

https://spl.kcp.co.kr/std/inquery

정상 응답 기준

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

요청 제한

초당 10회 이상 요청 시 요청 IP가 차단될 수 있습니다.

요청 정보

거래번호 조회 Request Body 예시

{
	"site_cd": "T0000",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"tno": "24452961394712",
	"pay_type": "PACA",
	"kcp_sign_data": "TVUZ6...KY3d8T6WXwNA=="
}

주문번호 조회 Request Body 예시

{
	"site_cd": "T0000",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"mod_ordr_idxx": "TEST2021072111324475",
	"tno": "20240721000000",
	"pay_type": "PACA",
	"kcp_sign_data": "TVUZ6...KY3d8T6WXwNA=="
}

조회 방식별 요청 차이

거래번호 조회

tno에 조회 대상 NHN KCP 거래번호를 전송합니다. mod_ordr_idxx는 전송하지 않아도 됩니다.

주문번호 조회

mod_ordr_idxx에 주문번호를 전송하고,
tno에는 결제일자와 0 여섯 자리를 조합한 YYYYMMDD000000 형식의 14자리 값을 전송합니다.

요청 파라미터

site_cd필수string5

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

kcp_cert_info필수string가변

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

kcp_sign_data필수string가변

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

tno필수string14

조회 키로 사용하는 값입니다.
거래번호 조회 시에는 조회 대상 NHN KCP 거래번호를 전송하고, 주문번호 조회 시에는 결제일자를 YYYYMMDD000000 형식으로 전송합니다.거래번호 조회 ex) "tno": "24452961394712"
주문번호 조회 ex) "tno": "20240721000000"

mod_ordr_idxxstring50

가맹점에서 관리하는 주문번호입니다. 주문번호를 조회 키로 사용할 때 전송합니다.ex) mod_ordr_idxx: TEST2021072111324475

pay_type필수string4

조회 요청 결제수단 코드입니다.
카드 : PACA
계좌이체 : PABK
가상계좌 : PAVC
휴대폰 : PAMC
상품권 : PATK
제휴간편결제 : PASG(SSG머니), PAKM(카카오머니), PANP(네이버페이포인트), PALP(엘포인트), PATO(토스머니)ex) pay_type: PACA

응답 정보

정상 처리 시 거래번호, 결제금액, 승인시각, 취소상태, 정산상태 및 결제수단별 상세 응답값이 리턴됩니다.
res_cd 값이 0000이 아니면 실패로 처리하며, 실패 시에는 res_cd, res_msg 외의 응답값이 리턴되지 않습니다.

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"res_en_msg": "processing completed",
	"tno": "24541454899962",
	"amount": "50000",
	"card_cd": "CCBC",
	"card_name": "BC카드",
	"app_no": "34218266",
	"app_time": "20241017170426",
	"quota": "00",
	"noinf": "N",
	"tax_flag": "TG03",
	"card_mny": "50000",
	"coupon_mny": "0",
	"stat_ca_cd": "STSR",
	"canc_card_yn": "N",
	"can_time": "",
	"rem_mny": "50000",
	"card_rem_mny": "50000",
	"coupon_rem_mny": "0",
	"shop_status": "STMR",
	"card_no": "9200200100007232",
	"partcanc_yn": "Y",
	"mall_taxno": "1138521083"
}

공통 응답 파라미터

res_cdstring4

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

res_msgstring100

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

res_en_msgstring100

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

tnostring14

NHN KCP 거래번호입니다. 승인, 조회, 취소 등 후속 처리 시 사용하므로 반드시 저장합니다.ex) tno: 24541454899962

amountnumber12

총 결제 금액입니다.ex) amount: 50000

카드 응답 파라미터

card_cdstring4

카드사 코드입니다.ex) card_cd: CCBC

card_namestring20

카드사 명입니다.ex) card_name: BC카드

card_nostring16

카드번호입니다. 일부 자리가 마스킹되어 리턴됩니다.ex) card_no: 9200200100007232

app_nostring8

카드사 승인번호입니다.ex) app_no: 34218266

app_timestring14

승인 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_time: 20241017170426

quotastring2

할부 개월 수입니다. 일시불은 00으로 리턴됩니다.ex) quota: 00

noinfstring1

무이자 여부입니다. 무이자인 경우 Y로 리턴됩니다.ex) noinf: N

card_mnynumber12

총 결제 금액 중 카드로 결제된 금액입니다.ex) card_mny: 50000

coupon_mnynumber12

총 결제 금액 중 쿠폰이 적용된 금액입니다.ex) coupon_mny: 0

payco_point_mnynumber12

PAYCO 포인트 결제 금액입니다. PAYCO 포인트 결제 건인 경우 리턴됩니다.ex) payco_point_mny: 5000

payco_rem_mnynumber12

PAYCO 포인트 취소 가능 금액입니다. PAYCO 포인트 부분취소 후 남은 PAYCO 포인트 결제 금액이며, PAYCO 포인트 결제 건인 경우 리턴됩니다.ex) payco_rem_mny: 0

card_rem_mnynumber12

카드 취소 가능 금액입니다. 콤마·소수점 없이 숫자만 리턴됩니다.ex) card_rem_mny: 1004

coupon_rem_mnynumber12

쿠폰 취소 가능 금액입니다. 콤마·소수점 없이 숫자만 리턴됩니다.ex) coupon_rem_mny: 0

rem_mnynumber12

취소 가능 금액입니다. 부분취소가 진행되었을 경우 취소 후 남은 총 결제 금액을 의미합니다.ex) rem_mny: 50000

stat_ca_cdstring4

카드 거래의 최종 결제 상태입니다. 거래상태 코드를 참고합니다.ex) stat_ca_cd: STSR

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STMR

canc_card_ynstring1

카드 취소 상태입니다. 취소된 경우 Y로 리턴됩니다.ex) canc_card_yn: N

can_timestring14

취소 시각입니다. YYYYMMDDHHMMSS 형식이며, 거래 상태가 STSC인 경우에만 리턴됩니다.ex) can_time: 20240613182041

tax_flagstring4

과세 유형입니다. TG01(과세), TG02(비과세), TG03(복합과세) 값으로 리턴됩니다.ex) tax_flag: TG03

partcanc_ynstring1

부분취소 가능 여부입니다. N이면 부분취소가 불가능한 거래 건입니다.ex) partcanc_yn: Y

mall_taxnostring10

가맹점 사업자번호입니다.ex) mall_taxno: 1138521083

계좌이체 응답 파라미터

bk_tidstring7

계좌이체 승인번호입니다.ex) bk_tid: 5622221

app_timestring14

계좌이체 결제 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_time: 20240617151535

bk_codestring4

계좌이체 은행 코드입니다.ex) bk_code: BK04

bk_namestring20

계좌이체 은행 명입니다.ex) bk_name: 국민은행

bk_mnynumber12

계좌이체 결제 금액입니다.ex) bk_mny: 5000

rem_mnynumber12

취소 가능 금액입니다. 부분취소가 진행되었을 경우 취소 후 남은 총 결제 금액을 의미합니다.ex) rem_mny: 5000

bk_rem_mnynumber12

계좌이체 취소 가능 금액입니다.ex) bk_rem_mny: 5000

stat_bk_cdstring4

계좌이체 거래의 최종 결제 상태입니다. 거래상태 코드를 참고합니다.ex) stat_bk_cd: STSR

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STSR

escw_ynstring1

에스크로 여부입니다. 에스크로 결제 건인 경우 Y로 리턴됩니다.ex) escw_yn: N

bk_receipt_gubnstring1

현금영수증 등록 여부입니다. Y(발급), S(자진발급), N(발급안됨), C(취소), P(부분취소) 값으로 리턴됩니다.ex) bk_receipt_gubn: Y

cash_authnostring9

현금영수증 승인번호입니다.ex) cash_authno: 123456789

bk_taxnostring20

현금영수증 등록정보입니다. 휴대폰번호, 사업자번호 또는 현금영수증 카드번호가 리턴됩니다.ex) bk_taxno: 01012345678

canc_bk_ynstring1

계좌이체 취소 여부입니다. 취소된 계좌이체 건은 Y로 리턴됩니다.ex) canc_bk_yn: Y

가상계좌 응답 파라미터

ipkum_moneynumber12

가상계좌 입금 금액입니다. 입금이 진행되지 않은 경우 0으로 리턴됩니다.ex) ipkum_money: 5000

bankcodestring4

가상계좌 입금 은행 코드입니다.ex) bankcode: BK03

banknamestring20

가상계좌 발급 은행 명입니다.ex) bankname: 기업은행

accountstring20

발급된 가상계좌 번호입니다.ex) account: 48000000000768

app_timestring14

가상계좌 발급 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_time: 20240617151535

va_datestring14

가상계좌 입금 마감 일자입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) va_date: 20240625235959

escw_ynstring1

에스크로 여부입니다. 에스크로 결제 건인 경우 Y로 리턴됩니다.ex) escw_yn: N

va_receipt_gubnstring1

현금영수증 등록 여부입니다. Y(발급), S(자진발급), N(발급안됨), C(취소), P(부분취소) 값으로 리턴됩니다.ex) va_receipt_gubn: Y

va_tr_codestring1

현금영수증 발행 용도입니다. 0은 소득공제, 1은 지출증빙입니다.ex) va_tr_code: 1

va_taxnostring20

현금영수증 등록정보입니다. 휴대폰번호, 사업자번호 또는 현금영수증 카드번호가 리턴됩니다.ex) va_taxno: 01012345678

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STSR

휴대폰 응답 파라미터

app_timestring14

휴대폰 결제 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_time: 20240617151535

hp_mnynumber12

휴대폰 결제 금액입니다.ex) hp_mny: 5000

commidstring3

휴대폰 통신사 코드입니다.ex) commid: LGT

mobile_nostring16

결제된 휴대폰 번호입니다.ex) mobile_no: 01012345678

stat_hp_cdstring4

휴대폰 거래의 최종 결제 상태입니다. 거래상태 코드를 참고합니다.ex) stat_hp_cd: STSR

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STSR

상품권 응답 파라미터

tk_van_codestring4

상품권사 코드입니다.ex) tk_van_code: SCBL

tk_app_nostring20

상품권 승인번호입니다.ex) tk_app_no: 240503055360435

tk_app_timestring14

상품권 승인 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) tk_app_time: 20240617151535

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STSR

제휴간편결제 응답 파라미터

kakaomny_mnynumber12

카카오머니 결제 금액입니다.ex) kakaomny_mny: 5000

app_kakaomny_timestring14

카카오머니 승인 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_kakaomny_time: 20240613091423

naverpoint_mnynumber12

네이버페이 포인트 결제 금액입니다.ex) naverpoint_mny: 5000

tossmny_mnynumber12

토스머니 결제 금액입니다.ex) tossmny_mny: 5000

ssgmny_mnynumber12

SSG머니 결제 금액입니다.ex) ssgmny_mny: 5000

lpoint_mnynumber12

엘포인트 결제 금액입니다.ex) lpoint_mny: 5000

app_easypoint_timestring14

제휴간편결제 승인 시각입니다. 네이버페이 포인트, 토스머니, 엘포인트 거래 등에서 리턴될 수 있습니다.ex) app_easypoint_time: 20240613091423

app_ssgmny_timestring14

SSG머니 승인 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.ex) app_ssgmny_time: 20240613091423

easypoint_rem_mnynumber12

제휴간편결제 거래 건의 취소 가능 금액입니다. 부분취소가 진행되었을 경우 취소 후 남은 총 결제 금액을 의미합니다.ex) easypoint_rem_mny: 5000

app_cash_receipt_nostring14

네이버페이 포인트 현금영수증 거래번호입니다.ex) app_cash_receipt_no: 24415062241991

service_corp_idstring4

제휴간편결제 기관 코드입니다.ex) service_corp_id: SCKA

shop_statusstring4

정산 상태입니다. 거래 건의 정산 상태가 리턴됩니다.ex) shop_status: STSR

구현 참고사항

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

JSP 샘플 구현 포인트 보기

거래조회 요청 시에는 site_cd + "^" + tno + "^" + pay_type 조합으로 서명데이터를 생성한 뒤, 조회 API에 JSON Body로 전송합니다. 주문번호 조회 시에는 mod_ordr_idxx와 결제일자 기반 tno를 함께 사용합니다.

// 거래 조회 API URL
String target_URL = "https://stg-spl.kcp.co.kr/std/inquery";

// 조회 정보
String tno = "24452961394712";
String pay_type = "PACA";

// 주문번호로 조회하는 경우
// mod_ordr_idxx에는 주문번호를, tno에는 결제일자 + 000000 형식의 14자리 값을 설정
// ex) tno = "20240721000000";

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

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

// 주문번호 조회 시에만 전송
json_req.put("mod_ordr_idxx", mod_ordr_idxx);

// 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, amount, 결제수단별 상태값 및 취소 가능 금액 저장
}