결제 승인 API

해당 페이지는 표준결제, 휴대폰결제, 에스크로, LITE PAY 가이드의 결제 승인 요청 및 응답에 대해 설명합니다.
결제 승인은 결제창 인증 결과로 받은 enc_data, enc_info, tran_cd를 이용해 NHN KCP 서버에 최종 승인 요청하는 API입니다.
승인 요청 시 가맹점 서버에 저장한 결제 금액(ordr_mony), 주문번호(ordr_no), 결제수단(pay_type)을 함께 전달하여 결제정보를 검증하세요.

거래 등록

결제창 호출

결제 승인

요약

대상 서비스

표준결제, 휴대폰결제, 에스크로, LITE PAY

HTTP Method

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

Content-Type

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

통신 보안

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

테스트 URL

https://stg-spl.kcp.co.kr/gw/enc/v1/payment

운영 URL

https://spl.kcp.co.kr/gw/enc/v1/payment

정상 응답 기준

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

요청 정보

Request Body 예시

{
	"site_cd": "T0000",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"enc_data": "1eOSNbDDMQCVqCHVNZGNPKZErG...I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf",
	"enc_info": "4dgxMICIupJdwMheYKVQI.Vd6...DnQ5i9Mu.JVz.C7JIK1NpdfDkdYd",
	"tran_cd": "00100000",
	"ordr_mony": "1000",
	"pay_type": "PACA",
	"ordr_no": "TEST123456789",
	"ordr_idxx": "TEST123456789"
}

요청 파라미터

site_cd필수string5

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

kcp_cert_info필수string가변

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

enc_data필수string가변

결제창 인증 결과 암호화 정보입니다.
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) enc_data: 1eOSNbDDMQCVqCHVNZGNPKZErG...I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf

enc_info필수string가변

결제창 인증 결과 암호화 정보입니다.
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) enc_info: 4dgxMICIupJdwMheYKVQI.Vd6...DnQ5i9Mu.JVz.C7JIK1NpdfDkdYd

tran_cd필수string8

결제창 인증 결과로 응답받은 요청 코드입니다. 결제 승인 요청 시 응답받은 값을 그대로 전송합니다. 임의로 변경할 수 없습니다.ex) tran_cd: 00100000

ordr_mony필수number12

승인 요청 금액입니다.ex) ordr_mony: 1000

pay_type필수string4

승인 요청 결제수단 코드입니다.
표준결제 / LITE PAY : PACA(카드), PABK(계좌이체), PAMC(휴대폰), PAPT(포인트), PATK(상품권)
휴대폰결제 : PAMC(휴대폰)
에스크로 : PACA(카드), PABK(계좌이체), PAVC(가상계좌), PAMC(휴대폰), PAPT(포인트), PATK(상품권)ex) pay_type: PACA

ordr_no필수string50

승인 요청 시 사용하는 주문번호입니다.ex) ordr_no: TEST123456789

ordr_idxxstring50

가맹점에서 관리하는 주문번호입니다. LITE PAY 결제 승인 요청 시 필수 값입니다.
중복되지 않는 유니크한 값으로 사용하고, 가맹점에서 반드시 저장합니다.ex) ordr_idxx: TEST123456789

응답 정보

정상 처리 시 응답 코드와 함께 거래번호, 승인 금액, 결제수단 및 결제수단별 상세 응답값이 리턴됩니다.

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"res_en_msg": "processing completed",
	"tno": "25536002322422",
	"amount": "1004",
	"pay_method": "PACA",
	"card_cd": "CCKM",
	"card_name": "국민카드",
	"card_no": "4673090000000032",
	"app_no": "46761234",
	"app_time": "20260101235959",
	"quota": "00",
	"coupon_mny": "0",
	"card_mny": "1004"
}

공통 응답 파라미터

res_cdstring4

응답 코드입니다. 일반 승인 정상 처리 시 0000을 리턴하며, 에스크로 결제에서 가상계좌 발급 정상 시 V000을 리턴합니다.ex) res_cd: 0000

res_msgstring100

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

res_en_msgstring100

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

tnostring14

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

amountnumber12

승인 금액입니다.ex) amount: 1004

escw_ynstring1

에스크로 적용 여부입니다. 에스크로 연동 응답에서 리턴될 수 있습니다.ex) escw_yn: Y

신용카드 응답 파라미터

일반 신용카드는 pay_method: PACA로 리턴됩니다. 카드 기반 제휴 간편결제는 아래 별도 항목도 함께 확인합니다.

card_cdstring4

카드 발급사 코드입니다.ex) card_cd: CCKM

card_namestring32

카드 발급사 명입니다.ex) card_name: 국민카드

card_nostring16

마스킹된 카드번호입니다. 카드번호 16자리 중 세 번째 구간이 0으로 마스킹되어 리턴됩니다.ex) card_no: 4673090000000032

app_nostring8

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

app_timestring14

카드 결제 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) app_time: 20260101235959

noinfstring1

무이자 적용 여부입니다. 무이자 결제인 경우 Y를 리턴합니다.ex) noinf: Y

noinf_typestring4

noinf가 Y일 때 무이자 유형을 리턴합니다. 카드사 이벤트 무이자는 CARD, 상점 부담 무이자는 SHOP입니다.ex) noinf_type: CARD

quotastring2

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

coupon_mnynumber12

쿠폰 할인 또는 PAYCO 포인트 사용 금액입니다.ex) coupon_mny: 0

card_mnynumber12

총 결제금액 중 신용카드 결제금액입니다.
쿠폰 또는 포인트 100% 결제 시 0이 리턴될 수 있으므로 최종 결제금액은 amount로 확인합니다.ex) card_mny: 1004

partcanc_ynstring1

부분취소 가능 여부입니다.ex) partcanc_yn: Y

card_bin_type_01string1

카드 개인/법인 구분 정보입니다. 개인은 0, 법인은 1입니다.ex) card_bin_type_01: 0

card_bin_type_02string1

카드 일반/체크 구분 정보입니다. 일반은 0, 체크는 1입니다.ex) card_bin_type_02: 0

payco_point_mnynumber12

PAYCO 포인트 사용 금액입니다.ex) payco_point_mny: 2000

isp_issuer_cdstring4

ISP 계열 카드 발급사 코드입니다. BC96은 케이뱅크카드, KM90은 카카오뱅크카드입니다.ex) isp_issuer_cd: KM90

isp_issuer_nmstring32

ISP 계열 카드 발급사 명입니다.ex) isp_issuer_nm: 카카오뱅크

계좌이체 응답 파라미터

pay_method: PABK인 경우 리턴됩니다.

bank_codestring4

계좌이체 은행 코드입니다.ex) bank_code: BK03

bank_namestring20

계좌이체 은행 명입니다.ex) bank_name: 기업은행

bk_mnynumber12

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

app_timestring14

계좌이체 결제 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) app_time: 20260131235959

cash_authnostring12

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

cash_nostring14

현금영수증 거래번호입니다.ex) cash_no: 20370466727800

가상계좌 응답 파라미터

에스크로 가상계좌에서 pay_method: PAVC로 리턴되며, 정상 발급 시 res_cd: V000입니다.

banknamestring20

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

bankcodestring4

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

accountstring20

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

va_datestring14

가상계좌 입금 마감일시입니다. 형식은 yyyyMMddHHmmss입니다.ex) va_date: 20260131235959

app_timestring14

가상계좌 발급시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) app_time: 20260101120000

휴대폰 응답 파라미터

pay_method: PAMC인 경우 리턴됩니다.

commidstring3

통신사 코드입니다.ex) commid: SKT

mobile_nostring11

휴대폰 번호입니다. 가운데 4자리는 0으로 마스킹되어 리턴됩니다.ex) mobile_no: 01000001234

hp_app_timestring14

휴대폰 결제 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) hp_app_time: 20260101120000

포인트 응답 파라미터

pay_method: PAPT인 경우 리턴됩니다.

pnt_amountnumber12

포인트 결제금액입니다.ex) pnt_amount: 1000

pnt_issuestring4

포인트 결제사 코드입니다.ex) pnt_issue: SCWB

pnt_app_nostring20

포인트 승인번호입니다.ex) pnt_app_no: 1234567890

pnt_app_timestring14

포인트 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) pnt_app_time: 20260131235959

pnt_receipt_gubnstring1

포인트 현금영수증 등록 여부입니다.ex) pnt_receipt_gubn: Y

cash_authnostring12

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

add_pntnumber12

포인트 적립 또는 사용 포인트입니다.ex) add_pnt: 1000

use_pntnumber12

가용 포인트입니다.ex) use_pnt: 5000

rsv_pntnumber12

승인 성공 시 리턴되는 총 포인트입니다.ex) rsv_pnt: 6000

상품권 응답 파라미터

pay_method: PATK인 경우 리턴됩니다.

tk_mnynumber12

상품권 결제금액입니다.ex) tk_mny: 1000

tk_van_codestring4

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

tk_app_nostring20

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

tk_app_timestring14

상품권 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) tk_app_time: 20260101235959

제휴간편결제(신용카드) 응답 파라미터

신용카드 결제 응답에 간편결제 구분값이 추가로 리턴됩니다.

card_other_pay_typestring4

신용카드 기반 제휴 간편결제 유형입니다.
OT12 PAYCO, OT01 삼성월렛, OT03 SSGPAY, OT11 L.PAY, OT13 카카오페이, OT16 네이버페이, OT21 애플페이, OT23 토스페이입니다.ex) card_other_pay_type: OT12

payco_point_mnynumber12

PAYCO 포인트 결제 시 사용된 PAYCO 포인트 금액입니다.ex) payco_point_mny: 1004

제휴간편결제(머니) 응답 파라미터

pay_method는 카카오머니 PAKM, 토스머니 PATO, SSG머니 PASG, 삼성월렛머니 PASM 등이 리턴됩니다.

easypoint_mnynumber12

총 결제금액 중 제휴 간편결제 머니 금액입니다.ex) easypoint_mny: 1004

app_easypoint_timestring14

제휴 간편결제 머니 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) app_easypoint_time: 20260131000000

service_corp_idstring4

제휴 간편결제사 기관 코드입니다.
SCKA 카카오머니, SCTO 토스머니, SCSM SSG머니, SCSA 삼성월렛머니입니다.ex) service_corp_id: SCKA

app_cash_receipt_ynstring1

현금영수증 발급 여부입니다. 발급은 Y, 미발급은 N입니다.ex) app_cash_receipt_yn: Y

app_cash_receipt_mnynumber12

현금영수증 발급 대상 금액입니다.ex) app_cash_receipt_mny: 1004

제휴간편결제(포인트) 응답 파라미터

네이버페이 포인트는 pay_method: PANP로 리턴됩니다.

easypoint_mnynumber12

총 결제금액 중 제휴 간편결제 포인트 금액입니다.ex) easypoint_mny: 1004

app_easypoint_timestring14

제휴 간편결제 포인트 승인시간입니다. 형식은 yyyyMMddHHmmss입니다.ex) app_easypoint_time: 20260131000000

service_corp_idstring4

제휴 간편결제사 기관 코드입니다. 네이버페이 포인트는 SCNA입니다.ex) service_corp_id: SCNA

app_cash_receipt_ynstring1

현금영수증 발급 여부입니다. Y는 발급, N은 미발급, S는 자진발급(네이버페이 포인트)입니다.ex) app_cash_receipt_yn: Y

app_cash_receipt_nostring14

현금영수증 거래번호입니다. 네이버페이 포인트 현금영수증 발급 시, app_cash_receipt_yn이 Y 또는 S인 경우 리턴됩니다.ex) app_cash_receipt_no: 12345678912345

app_cash_receipt_mnynumber12

현금영수증 발급 대상 금액입니다.ex) app_cash_receipt_mny: 1004

구현 참고사항

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

JSP 샘플 구현 포인트 보기

표준결제, 에스크로, LITE PAY 샘플은 결제창 인증 결과로 받은 암호화 정보를 서버에서 승인 API로 전달하고, 응답받은 거래번호와 결제수단별 응답값을 가맹점 DB에 저장하는 흐름입니다.

// 결제 승인 API URL
String target_URL = "https://stg-spl.kcp.co.kr/gw/enc/v1/payment";

// 공통 요청 JSON 구성
json_req.put("site_cd", site_cd);
json_req.put("kcp_cert_info", kcp_cert_info);
json_req.put("enc_data", enc_data);
json_req.put("enc_info", enc_info);
json_req.put("tran_cd", tran_cd);

// 결제정보 검증용 값
json_req.put("ordr_mony", ordr_mony);
json_req.put("pay_type", pay_type);
json_req.put("ordr_no", ordr_no);

// LITE PAY 연동 시 샘플 기준으로 함께 전달
json_req.put("ordr_idxx", ordr_idxx);

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

// 정상 응답 처리
res_cd = (String)json_res.get("res_cd");

// 일반 승인 정상: 0000
// 가상계좌 발급 정상: V000
if ("0000".equals(res_cd) || "V000".equals(res_cd)) {
  // tno, amount, pay_method 및 결제수단별 응답값 저장
}