Guide > LITE PAY

LITE PAY

REST API로 간편 연동

설치 불필요 JSON POST 세 번 PC / Mobile 공통

모듈 설치 불필요 JSON API 방식 PC / Mobile 공통 흐름 HTTPS POST

간편연동 특징

🔌 모듈 없이 바로 연동

DLL·JAR 설치 없이 HTTPS JSON 요청만으로 결제를 연동합니다. 서버 언어에 관계없이 동일한 방식으로 연동할 수 있습니다.

📱 PC·Mobile 통합 흐름

PC와 모바일을 별도로 분기할 필요 없습니다. reg_type 파라미터 하나로 결제창 유형을 선택하면 됩니다.

🎨 결제 UI 개발 불필요

KCP에서 제공하는 결제창을 pay_url 호출만으로 사용할 수 있어 별도 결제 UI를 개발할 필요가 없습니다.

🔒 결제정보 검증

가맹점 DB에 저장된 금액, 결제수단을 승인 요청 시 함께 전달하면 KCP 서버가 위변조 여부를 자동으로 검증합니다.

서비스 흐름도

거래등록 → 결제창 인증 → 결제승인 순으로 진행됩니다.

1. 거래등록

결제에 필요한 주문 정보를 NHN KCP 서버에 등록합니다. 등록이 완료되면 결제창을 직접 호출할 수 있는 pay_url이 응답됩니다.

reg_type으로 PC(web)·모바일(mobile) 결제창을 선택하면, 그에 맞는 pay_url이 리턴됩니다.
ret_URL은 결제창의 인증 데이터를 전달받을 가맹점 서버 URL입니다.

거래등록 API URL

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

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

요청 파라미터

site_cd 필수

String 5byte

NHN KCP와 계약 시 발급된 가맹점 고유 사이트코드입니다. 영문 대문자 또는 영문 대문자+숫자로 구성됩니다.

ex) "site_cd" : "T0000"

kcp_cert_info 필수

String 가변

NHN KCP에서 발급하는 서비스 인증서입니다. 상점관리자의 인증센터에서 다운받은 pem 파일 내용을 직렬화하여 사용합니다.

ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHBy4lYNG7ojANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJLUjEOMAwGA1UECAwFU2VvdWwxEDAOBgNVBAcMB0d1cm8tZ3UxFTATBgNVBAoMDE5ITktDUCBDb3JwLjETMBEGA1UECwwKSVQgQ2VudGVyLjEWMBQGA1UEAwwNc3BsLmtjcC5jby5rcjAeFw0yMTA2MjkwMDM0MzdaFw0yNjA2MjgwMDM0MzdaMHAxCzAJBgNVBAYTAktSMQ4wDAYDVQQIDAVTZW91bDEQMA4GA1UEBwwHR3Vyby1ndTERMA8GA1UECgwITG9jYWxXZWIxETAPBgNVBAsMCERFVlBHV0VCMRkwFwYDVQQDDBAyMDIxMDYyOTEwMDAwMDI0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAppkVQkU4SwNTYbIUaNDVhu2w1uvG4qip0U7h9n90cLfKymIRKDiebLhLIVFctuhTmgY7tkE7yQTNkD+jXHYufQ/qj06ukwf1BtqUVru9mqa7ysU298B6l9v0Fv8h3ztTYvfHEBmpB6AoZDBChMEua7Or/L3C2vYtU/6lWLjBT1xwXVLvNN/7XpQokuWq0rnjSRThcXrDpWMbqYYUt/CL7YHosfBazAXLoN5JvTd1O9C3FPxLxwcIAI9H8SbWIQKhap7JeA/IUP1Vk4K/o3Yiytl6Aqh3U1egHfEdWNqwpaiHPuM/jsDkVzuS9FV4RCdcBEsRPnAWHz10w8CX7e7zdwIDAQABox0wGzAOBgNVHQ8BAf8EBAMCB4AwCQYDVR0TBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAg9lYy+dM/8Dnz4COc+XIjEwr4FeC9ExnWaaxH6GlWjJbB94O2L26arrjT2hGl9jUzwd+BdvTGdNCpEjOz3KEq8yJhcu5mFxMskLnHNo1lg5qtydIID6eSgew3vm6d7b3O6pYd+NHdHQsuMw5S5z1m+0TbBQkb6A9RKE1md5/Yw+NymDy+c4NaKsbxepw+HtSOnma/R7TErQ/8qVioIthEpwbqyjgIoGzgOdEFsF9mfkt/5k6rR0WX8xzcro5XSB3T+oecMS54j0+nHyoS96/llRLqFDBUfWn5Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----"

kcp_sign_data 필수

String 가변

요청 데이터의 무결성을 증명하기 위해 가맹점 개인키로 서명한 값입니다.
특정 필드를 조합한 후 SHA256withRSA 방식으로 인코딩하여 생성합니다.
조합필드 : site_cd + "^" + good_mny + "^" + pay_method + "^" + reg_type + "^" + ordr_idxx

ex) "kcp_sign_data" : "eyJhbGciOiJSUzI1NiJ9..."

서명데이터 생성 가이드

ordr_idxx 필수

String 50byte

가맹점에서 생성하는 주문번호입니다. 중복되지 않는 고유 값으로 생성해야 하며, 결제창 호출 및 승인 단계에서 동일한 값을 사용합니다.

ex) "ordr_idxx" : "ORDER20240101001"

pay_method 필수

String 4byte

결제수단을 설정합니다.

신용카드 : CARD / 계좌이체 : BANK / 휴대폰 : MOBX / 상품권 : GIFT / 포인트 : TPNT

ex) "pay_method" : "CARD"

good_mny 필수

Number 12byte

결제금액입니다.

ex) "good_mny" : 10000

good_name 필수

String 100byte

결제창에 노출되는 상품명입니다.

ex) "good_name" : "테스트 상품"

reg_type 필수

String 6byte

결제창 유형을 선택합니다. PC와 모바일 환경을 이 값 하나로 분기할 수 있습니다.

PC 결제창 : web / 모바일 결제창 : mobile

ex) "reg_type" : "web"

ret_URL 필수

String 256byte

카드사 인증 완료 후 KCP가 인증 데이터(enc_data, enc_info)를 POST로 전달하는 가맹점 서버 URL입니다. 반드시 서버 측 처리가 가능한 URL을 입력해야 합니다.

ex) "ret_URL" : "https://쇼핑몰주문처리서버/return"

fail_url 필수

String 256byte

인증 실패 시 리다이렉트할 가맹점 URL입니다.

ex) "fail_url" : "https://쇼핑몰주문처리서버/fail"

요청 예시

거래등록 요청 Body (JSON)

{
  "site_cd"      : "T0000",                          // 사이트코드
  "kcp_cert_info": "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHBy4lYNG7ojANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJLUjEOMAwGA1UECAwFU2VvdWwxEDAOBgNVBAcMB0d1cm8tZ3UxFTATBgNVBAoMDE5ITktDUCBDb3JwLjETMBEGA1UECwwKSVQgQ2VudGVyLjEWMBQGA1UEAwwNc3BsLmtjcC5jby5rcjAeFw0yMTA2MjkwMDM0MzdaFw0yNjA2MjgwMDM0MzdaMHAxCzAJBgNVBAYTAktSMQ4wDAYDVQQIDAVTZW91bDEQMA4GA1UEBwwHR3Vyby1ndTERMA8GA1UECgwITG9jYWxXZWIxETAPBgNVBAsMCERFVlBHV0VCMRkwFwYDVQQDDBAyMDIxMDYyOTEwMDAwMDI0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAppkVQkU4SwNTYbIUaNDVhu2w1uvG4qip0U7h9n90cLfKymIRKDiebLhLIVFctuhTmgY7tkE7yQTNkD+jXHYufQ/qj06ukwf1BtqUVru9mqa7ysU298B6l9v0Fv8h3ztTYvfHEBmpB6AoZDBChMEua7Or/L3C2vYtU/6lWLjBT1xwXVLvNN/7XpQokuWq0rnjSRThcXrDpWMbqYYUt/CL7YHosfBazAXLoN5JvTd1O9C3FPxLxwcIAI9H8SbWIQKhap7JeA/IUP1Vk4K/o3Yiytl6Aqh3U1egHfEdWNqwpaiHPuM/jsDkVzuS9FV4RCdcBEsRPnAWHz10w8CX7e7zdwIDAQABox0wGzAOBgNVHQ8BAf8EBAMCB4AwCQYDVR0TBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAg9lYy+dM/8Dnz4COc+XIjEwr4FeC9ExnWaaxH6GlWjJbB94O2L26arrjT2hGl9jUzwd+BdvTGdNCpEjOz3KEq8yJhcu5mFxMskLnHNo1lg5qtydIID6eSgew3vm6d7b3O6pYd+NHdHQsuMw5S5z1m+0TbBQkb6A9RKE1md5/Yw+NymDy+c4NaKsbxepw+HtSOnma/R7TErQ/8qVioIthEpwbqyjgIoGzgOdEFsF9mfkt/5k6rR0WX8xzcro5XSB3T+oecMS54j0+nHyoS96/llRLqFDBUfWn5Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----",  // 서비스 인증서
  "kcp_sign_data": "eyJhbGciOiJSUzI1NiJ9...",          // 서명 데이터
  "ordr_idxx"    : "ORDER20240101001",               // 주문번호
  "pay_method"   : "CARD",                           // 결제수단
  "good_mny"     : "10000",                             // 결제금액
  "good_name"    : "테스트 상품",                      // 상품명
  "reg_type"     : "web",                            // 결제창 유형
  "ret_URL"      : "https://your-site.com/payment/return", // 인증결과 수신 URL
  "fail_url"     : "https://your-site.com/payment/fail"    // 실패 리다이렉트 URL
}

응답

결제창 URL이 발급됩니다

거래등록이 정상 처리되면 응답 본문에 pay_url이 포함됩니다. 이 URL이 곧 결제창 진입 주소입니다.
고객 브라우저를 이 URL로 리다이렉트하는 것만으로 NHN KCP 결제창이 실행됩니다.

pay_url은 응답받은 값 그대로 사용하세요.
URL에 파라미터를 추가하거나 임의로 가공하면 결제창이 정상적으로 열리지 않습니다.

🖥 PC 결제창

reg_type: "web"으로 요청하면 PC에 최적화된 결제창 URL이 리턴됩니다. 팝업이 아닌 전체 페이지 전환(리다이렉트) 방식으로 호출해야 합니다.

📱 모바일 결제창

reg_type: "mobile"로 요청하면 모바일에 최적화된 URL이 리턴됩니다. 카드사 앱 연동을 위해 반드시 리다이렉트 방식으로 호출하세요.

2. 결제창 호출

거래등록에서 응답받은 pay_url로 고객 브라우저를 이동시켜 결제창을 실행합니다.
NHN KCP가 제공하는 결제창이 열리므로 별도의 결제 UI를 개발할 필요가 없습니다.

pay_url은 반드시 페이지 전환(리다이렉트) 방식으로 호출하세요.
iframe이나 팝업 방식으로 호출하면 일부 카드사 앱 연동이나 브라우저 환경에 따라 결제가 원활하게 진행되지 않을 수 있습니다.

결제수단별 전달 파라미터

pay_url 호출 시 함께 전달해야 하는 파라미터는 결제수단에 따라 다릅니다.
ordr_idxx는 공통 필수이며, 일부 결제수단은 추가 파라미터가 필요합니다.

결제수단

전달 파라미터

신용카드 / 계좌이체

ordr_idxx

휴대폰

ordr_idxx shop_user_id

상품권

ordr_idxx shop_user_id van_code

포인트

ordr_idxx van_code pt_memcorp_cd

파라미터 상세

ordr_idxx 필수

String 50byte

거래등록 단계에서 가맹점이 생성한 주문번호입니다. NHN KCP는 이 값으로 등록된 거래를 식별합니다.
가맹점 DB에 저장된 값을 그대로 사용하세요. 임의로 변경하면 결제 처리가 실패합니다.

ex) "ordr_idxx" : "ORDER20240101001"

shop_user_id 휴대폰 · 상품권 필수

String 50byte

쇼핑몰에서 관리하는 회원 ID입니다.

ex) "shop_user_id" : "testuser01"

van_code 포인트 · 상품권 필수

String 4byte

포인트 및 상품권 결제에서 사용하는 VAN사 코드입니다. 계약된 기관의 코드를 입력하세요.
포인트 : 베네피아 SCWB / OK 캐시백 SCSK
상품권 : 컬쳐랜드 SCCL / 도서상품권 SCBL

ex) "van_code" : "SCCL:SCBL"

코드표 가이드

pt_memcorp_cd 베네피아 포인트 필수

String 4byte

베네피아 소속사 코드입니다.

ex) "pt_memcorp_cd" : "5555"

응답

인증 결과가 ret_URL로 응답됩니다.

결제창에서 인증이 성공할 경우 ret_URL로 인증결과가 응답됩니다.
인증 실패의 경우 fail_url로 처리됩니다. 인증결과로는 결제창의 인증데이터를 암호화한 enc_data, enc_info 가 전달됩니다.

3. 결제 승인 요청

ret_URL로 전달받은 인증 암호화 데이터(enc_data, enc_info)를 수신한 즉시, 결제 승인 API를 호출해야 합니다.

인증 데이터(enc_data, enc_info, tran_cd)는 받은 값 그대로 전달하고, 금액·결제수단·주문번호는 가맹점 DB의 원본 값을 사용하여 위변조를 방지하세요.

결제 승인 API URL

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

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

위변조 방지 : ordr_mony, pay_type는 클라이언트에서 전달받은 값이 아닌 가맹점 DB에 저장된 원본 데이터를 사용하세요.

요청 파라미터

site_cd 필수

String 5byte

NHN KCP와 계약 시 발급된 가맹점 고유 사이트코드입니다.

ex) "site_cd" : "T0000"

kcp_cert_info 필수

String 가변

NHN KCP에서 발급하는 서비스 인증서입니다. pem 파일 내용을 직렬화하여 사용합니다.

enc_data 필수

String 가변

결제창 인증결과 암호화 데이터입니다. ret_url로 전달받은 값을 그대로 사용합니다. 임의로 변경 불가합니다.

ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL..."

enc_info 필수

String 가변

결제창 암호화 키 정보입니다. ret_url로 전달받은 값을 그대로 사용합니다. 임의로 변경 불가합니다.

tran_cd 필수

String 8byte

결제 요청 코드입니다. 결제창에서 응답받은 값을 그대로 설정합니다.

ex) "tran_cd" : "00100000"

ordr_idxx 필수

String 50byte

가맹점 주문번호입니다. 거래등록, 결제창 호출단계와 동일한 값을 사용하세요.

ex) "ordr_idxx" : "ORDER20240101001"

ordr_mony 필수

Number 12byte

결제금액 검증 파라미터입니다. 가맹점 DB에 저장된 원본 금액을 사용해야 합니다. 클라이언트에서 전달받은 값은 사용하지 마세요.

ex) "ordr_mony" : "10000"

pay_type 필수

String 4byte

결제수단 검증 파라미터입니다. 가맹점 DB에 저장된 결제수단을 설정하여 전달합니다.

카드 : PACA / 계좌이체 : PABK / 휴대폰 : PAMC / 포인트 : PAPT / 상품권 : PATK

ex) "pay_type" : "PACA"

ordr_no 필수

String 50byte

주문번호 검증 파라미터입니다. 가맹점 DB에 저장된 주문번호를 설정하여 전달합니다.

ex) "ordr_no" : "ORDER20240101001"

결제 승인 응답

결제 승인에 성공하면 res_cd에 "0000"이 리턴되며, 결제수단별 응답 파라미터에 값이 채워져 리턴됩니다.

// 신용카드 응답 데이터 예시

{
  "res_cd":"0000",
  "res_msg":"정상처리",
  "pay_method":"PACA",
  "order_no":"TEST123456789",
  "amount":"1000",
  "card_mny":"1000",
  "coupon_mny":"0",
  "card_no":"4673090000000032",
  "quota":"00",
  "tno":"24346915432487",
  "card_cd":"CCKM",
  "card_name":"국민카드",
  "app_no":"78710726"
}

🗄 가맹점 DB 필수 저장 항목 — 분쟁·환불·정산 시 필수 근거가 됩니다

res_cd / res_msg 응답코드·메시지. 장애 대응 및 로그 추적에 필요합니다.

tno KCP 거래번호. 취소·환불·조회 시 반드시 필요합니다.

amount 승인된 결제금액. 정산 및 분쟁 해결의 기준이 됩니다.

order_no 가맹점 주문번호. 거래와 주문을 연결하는 키입니다.

결제 승인 응답 전체 파라미터는 API Reference를 확인해 주세요.

4. 운영 전환

개발 및 테스트가 완료된 후, 아래 항목을 실제 운영 값으로 교체하세요.

변경 항목

사이트코드

T0000 → 계약 시 발급된 사이트코드

거래등록 API URL

stg-spl.kcp.co.kr → spl.kcp.co.kr

결제승인 API URL

stg-spl.kcp.co.kr → spl.kcp.co.kr

서비스 인증서 발급 경로

상점관리자 > 기술관리센터 > 인증센터 > KCP PG-API

서비스 인증서 안내

유효기간

5년. 만료 30일 전부터 재발급이 가능합니다.

개인키 분실 시

폐기 후 재발급이 필요합니다. 재발급 전까지 승인·취소·조회 등 모든 서비스 이용이 불가합니다.