LITE PAY 거래등록 API

해당 페이지는 LITE PAY 가이드의 1. 거래등록 하기에 대해 설명합니다.
LITE PAY 거래등록은 결제창을 호출하기 전에 결제에 필요한 주문데이터를 NHN KCP 서버에 등록하는 API입니다.
먼저 Guide에서 전체 연동 흐름을 확인하고, 거래등록이 정상 처리되면 결제창 주소인 PayUrl을 응답받습니다.

거래 등록

결제창 호출

결제 승인

요약

HTTP Method

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

Content-Type

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

통신 보안

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

테스트 URL

https://stg-spl.kcp.co.kr/std/brpay/treg

운영 URL

https://spl.kcp.co.kr/std/brpay/treg

정상 응답 기준

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

요청 정보

Request Body 예시

{
	"site_cd": "T0000",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"ordr_idxx": "TEST123456789",
	"pay_method": "CARD",
	"good_mny": "1000",
	"good_name": "운동화",
	"reg_type": "web",
	"ret_URL": "https://example.com/kcp/lite/return",
	"fail_url": "https://example.com/kcp/lite/fail",
	"kcp_sign_data": "ceCJUAwjijT7+VKVt+...P6wPmg=="
}

요청 파라미터

site_cd필수String5

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

kcp_cert_info필수String가변

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

ordr_idxx필수String50

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

pay_method필수String4

이용할 결제수단 코드입니다.
카드 : CARD
계좌 : BANK
휴대폰 : MOBX
상품권 : GIFT
포인트 : TPNTex) pay_method: CARD

good_mny필수Number12

결제 금액입니다. 콤마·소수점 없이 숫자만 입력합니다.ex) good_mny: 1000

good_name필수String100

상품명입니다.ex) good_name: 운동화

reg_type필수String가변

거래등록 정상 처리 시 리턴받는 PayUrl의 결제창 유형을 선택합니다.
PC 결제창은 web, 모바일 결제창은 mobile로 설정합니다.ex) reg_type: web

ret_URL필수String256

인증 완료 후 결과를 리턴받을 가맹점 응답 주소입니다. https로 시작하는 가맹점 도메인 주소를 입력합니다.ex) ret_URL: https://example.com/kcp/lite/return

fail_url필수String256

NHN KCP 결제창 인증 실패 시 리다이렉트되는 가맹점 페이지입니다.ex) fail_url: https://example.com/kcp/lite/fail

kcp_sign_data필수String가변

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

응답 정보

정상 처리 시 Code 값으로 0000이 리턴됩니다. 이후 결제창 실행 단계에서 approvalKey와 PayUrl을 사용합니다.

Response Body 예시

{
	"Code": "0000",
	"Message": "Success",
	"approvalKey": "ECM9GRIdOnDBP9hFp8ORYgcHyKIPdQ/iE35VBPEo1cQ=",
	"PayUrl": "https://test-brpay.kcp.co.kr/SPAY/UTF-8/...",
	"traceNo": "T0000LY89KT2OX12",
	"paymentMethod": "CARD"
}

응답 파라미터

CodeString4

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

MessageString100

응답 메시지입니다. 정상 처리된 경우 Success를 리턴합니다.ex) Message: Success

approvalKeyString가변

거래 인증 키입니다. 리턴받은 값을 그대로 사용하며 결제창 실행 파라미터 approval_key 값에 설정합니다.ex) approvalKey: ECM9GRIdOnDBP9h...

PayUrlString가변

결제창 주소입니다. 리턴받은 값을 그대로 사용합니다.ex) PayUrl: https://test-brpay.kcp.co.kr/SPAY/UTF-8/...

traceNoString가변

추적번호입니다.ex) traceNo: T0000LY89KT2OX12

paymentMethodString4

거래등록 요청에 대한 결제수단입니다. 요청 시 전달한 결제수단과 일치하는지 확인합니다.ex) paymentMethod: CARD

구현 참고사항

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

JSP 샘플 구현 포인트 보기

LITE PAY JSP 샘플에서는 서버에서 거래등록 API를 호출하고, 정상 응답 시 PayUrl을 이용해 결제창 실행 단계로 이동합니다.

// 거래등록 API URL
String target_URL = "https://stg-spl.kcp.co.kr/std/brpay/treg";

// 서명데이터 생성
String targetData = site_cd + "^" + good_mny + "^" + pay_method + "^" + reg_type + "^" + ordr_idxx;
String kcp_sign_data = makeSignatureData(targetData);

// 요청 JSON 구성
json_req.put("site_cd", site_cd);
json_req.put("kcp_cert_info", kcp_cert_info);
json_req.put("pay_method", pay_method);
json_req.put("reg_type", reg_type);
json_req.put("ret_URL", ret_URL);
json_req.put("fail_url", fail_url);
json_req.put("kcp_sign_data", kcp_sign_data);
json_req.put("ordr_idxx", ordr_idxx);
json_req.put("good_mny", good_mny);
json_req.put("good_name", good_name);

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

// 정상 응답이면 PayUrl로 결제창 실행
PayUrl = (String)json_res.get("PayUrl");
res_cd = (String)json_res.get("Code");