거래등록 API

해당 페이지는 표준결제, 휴대폰결제, 자동결제, 에스크로 가이드의 1. Mobile 거래등록 하기에 대해 설명합니다.
거래등록은 Mobile 환경에서 결제창 또는 배치키 발급 결제창을 호출하기 전에 주문 및 결제 정보를 NHN KCP 서버에 등록하는 API입니다.
먼저 Guide에서 전체 연동 흐름을 확인하고, 거래등록이 정상 처리되면 응답받은 approvalKey와 PayUrl을 결제창 호출 단계에서 사용하세요.

거래 등록

결제창 호출

결제 승인

요약

대상 서비스

표준결제, 휴대폰결제, 자동결제, 에스크로

HTTP Method

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

Content-Type

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

통신 보안

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

테스트 URL

https://testsmpay.kcp.co.kr/trade/register.do

운영 URL

https://smpay.kcp.co.kr/trade/register.do

정상 응답 기준

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

요청 정보

Request Body 예시

{
	"site_cd": "T0000",
	"ordr_idxx": "TEST123456789",
	"good_mny": "1004",
	"good_name": "운동화",
	"pay_method": "CARD",
	"Ret_URL": "https://example.com/kcp/return",
	"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5_1 like Mac OS X)"
}

서비스별 요청 차이

표준결제

pay_method는 CARD, BANK, MOBX, TPNT, GIFT 중 하나를 사용합니다.

에스크로

pay_method에 VCNT 가상계좌가 추가됩니다.
에스크로 거래등록 시 escw_used는 필수이며, 에스크로 이용은 Y, 일반결제 처리는 N으로 설정합니다.

자동결제

pay_method는 일반 결제수단 코드가 아니라 AUTH 고정값을 사용합니다.

요청 파라미터

site_cd필수string5

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

ordr_idxx필수string50

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

good_mny필수number12

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

good_name필수string100

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

pay_method필수string4

거래등록 결제수단 코드입니다.
표준결제 : CARD(카드), BANK(계좌이체), MOBX(휴대폰), TPNT(포인트), GIFT(상품권)
휴대폰결제 : MOBX(휴대폰)
에스크로 : CARD(카드), BANK(계좌이체), VCNT(가상계좌), MOBX(휴대폰), TPNT(포인트), GIFT(상품권)
자동결제 : AUTH 고정값ex) pay_method: CARD

Ret_URL필수string256

인증 완료 후 결과를 리턴받을 가맹점 응답 주소입니다. https로 시작하는 가맹점 도메인 주소를 입력합니다.
※ 거래등록 시 전송한 Ret_URL 값과 동일한 값을 결제창 호출 form에도 함께 전송해야 합니다.
※ 콜백 응답 Body는 EUC-KR로 인코딩되어 전달되므로, 가맹점 서버에서 디코딩 처리가 필요합니다.ex) Ret_URL: https://example.com/kcp/return

escw_used에스크로 필수string1

에스크로 서비스의 거래등록 요청에서 필수로 전송하는 사용 여부 값입니다. 에스크로 이용 시 Y, 일반결제 처리 시 N으로 설정합니다.ex) escw_used: Y

user_agentString가변

사용 OS 또는 브라우저 User-Agent 정보입니다.ex) user_agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_5_1 like Mac OS X)

응답 정보

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

Response Body 예시

{
	"Code": "0000",
	"Message": "Success",
	"approvalKey": "ockLyC3QH...iEPEo1cQ=",
	"PayUrl": "https://testsmpay.kcp.co.kr/pay/mobileGW.kcp",
	"hashData": "cn447332cab4...93f6736653bb",
	"traceNo": "T0000LY89KT2OX12",
	"paymentMethod": "CARD"
}

응답 파라미터

CodeString4

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

MessageString100

응답 메시지입니다.ex) Message: Success

approvalKeystring가변

거래 인증 키입니다. 거래등록 응답으로 받은 approvalKey 값을 변경하지 않고, 다음 결제창 호출 단계의 approval_key 파라미터 값으로 전달합니다.ex) approvalKey: ockLyC3QH...

PayUrlstring가변

결제창 호출 주소입니다. 거래등록 응답으로 리턴된 PayUrl 값을 그대로 사용합니다.ex) PayUrl: https://testsmpay.kcp.co.kr/pay/mobileGW.kcp

hashDataString가변

해쉬 데이터입니다.ex) hashData: cn447332cab4...

traceNoString가변

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

paymentMethodString가변

거래등록 요청에 대한 결제수단입니다.ex) paymentMethod: CARD

구현 참고사항

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

JSP 샘플 구현 포인트 보기

JSP/PHP 샘플에서는 서버에서 거래등록 API를 호출하고, 정상 응답 시 approvalKey와 PayUrl을 결제창 호출 페이지로 전달합니다.

// 거래등록 API URL
String target_URL = "https://testsmpay.kcp.co.kr/trade/register.do";

// 공통 요청 JSON 구성
json_req.put("site_cd", site_cd);
json_req.put("ordr_idxx", ordr_idxx);
json_req.put("good_mny", good_mny);
json_req.put("good_name", good_name);

// pay_method 서비스별 설정
// 표준결제: CARD, BANK, MOBX, TPNT, GIFT
// 휴대폰결제: MOBX
// 에스크로: CARD, BANK, VCNT, MOBX, TPNT, GIFT
// 자동결제: AUTH 고정값
json_req.put("pay_method", pay_method);

json_req.put("Ret_URL", Ret_URL);

// 에스크로 사용 시 필수
json_req.put("escw_used", escw_used);

// 선택값
json_req.put("user_agent", user_agent);

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

// 정상 응답이면 approvalKey, PayUrl을 결제창 호출 단계로 전달
if ("0000".equals(Code)) {
  // approvalKey, PayUrl 등을 다음 페이지로 전달
}