수기결제 연동하기


API 연동하기

NHN KCP에서 제공하는 수기 결제(인증/비인증) API 연동 가이드를 안내합니다.
수기 결제는 직접 카드 정보를 입력해서 결제하는 방식으로 카드 인증 여부에 따라 인증/비인증 결제로 나뉩니다.

API Download

라이브러리와 샘플은 다운로드 자료실을 참조해주세요.


승인요청하기

상점,결제,주문,카드 정보를 포함한 요청 데이터로 승인요청 하세요.

<!-- API 호출 -->

1https://spl.kcp.co.kr/gw/hub/v1/payment

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


승인요청데이터

승인요청 데이터는 Json String 전송방식으로 요청 하세요.

수기결제 인증방식에 대한 승인요청데이터 예시이며
비인증 방식의 경우 'card_taxno(카드인증정보)','card_pwd(카드비밀번호)'를 제외해서 요청해주세요

승인요청을 위한 kcp_cert_info 인증서 데이터 발급은 참고사항의 서버인증서페이지와 아래 가이드를 참고해주세요.

<!-- 승인요청 데이터 -->

1{
1 "site_cd":"T1234",
2 "kcp_cert_info":"-----BEGIN CERTIFICATE-----MIID3DCCAsSgAwIBAgIJAM...=-----END CERTIFICATE-----",
3 "pay_method":"CARD",
4 "cust_ip":"",
5 "amount":"1000",
6 "card_mny":"1000",
7 "currency":"410",
8 "quota":"00",
9 "ordr_idxx":"TEST1234567890",
10"good_name":"테스트 상품",
11"buyr_name":"홍길동",
12"buyr_mail":"test@kcp.co.kr",
13"buyr_tel2":"01000000000",
14"card_tx_type":"11121000",
15"card_no":"1234567800000000",
16"card_expiry":"2607",
17"card_taxno":"951010",
18"card_pwd":"00"
19}
Type : json / application

결제 응답 전문의 경우 동일한 형태로 리턴됩니다.


서비스 인증서

NHN KCP 발급 인증서 내 데이터 값 추출,
가맹점 인증을 위해 KCP로부터 발급 받은 인증서 정보를 text 형식으로 전달해주셔야 하며,
인증서의 text 값을 데이터 직렬화하여 kcp_cert_info 의 value 값으로 전달하시기 바랍니다.

kcp_cert_info는 결제 승인 취소 거래등록 조회 시에 필요합니다.

KCP 서비스 인증서 관련 상세 내용은 서버 인증서 페이지를 참고 부탁 드립니다.


승인요청 파라미터 가이드

승인요청 파라미터

string5

site_cd

KCP발급 사이트(상점)코드
가입 시 발송해드리는 연동메일 참조 / 테스트코드 : T0000


string가변

kcp_cert_info

KCP 인증서정보(직렬화)
관리자 페이지에서 발급받은 인증서 정보(직렬화 하여 요청)


string4

pay_method

결제수단
CARD : 고정값


string15

cust_ip

요청자IP


number12

amount

총 결제금액
결제금액은 숫자 이외의 문자(콤마 등)는 허용하지 않습니다
ex) 1004


number12

card_mny

카드 결제금액
결제금액은 숫자 이외의 문자(콤마 등)는 허용하지 않습니다
ex) 1004


string3

currency

화폐단위
※ 원화 - WON : 410 / 달러 - USD : 840


number2

quota

할부개월 수
할부결제 시에 사용할 할부 개월을 입력하는 변수로 반드시 두 자리의 숫자 값으로 입력해주시기 바랍니다.
ex) 5개월의 경우 "05"로 설정


string40

ordr_idxx

가맹점에서 자체 생성한 주문번호
가맹점에서 주문 정보를 관리하기 위해 자체 생성한 주문번호를 이 변수에 입력해 주시기 바랍니다.
ex) TEST1235467890


string100

good_name

상품명
상품의 정보를 간략하게 입력하여 주시기 바랍니다.
※ 필수 정보는 아니지만 고객 안내 및 주문정보 관리를 위하여 정확한 상품명을 넘겨야 합니다.


string30

buyr_name

주문자 명
ex) 홍길동


string50

buyr_mail

주문자 E-Mail
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.


string20

buyr_tel2

주문자 휴대폰번호
('-' 사용 무관)


string8

card_tx_type

카드 전문 유형
11121000 : 인증방식(고정값)
11111000 : 비인증방식(고정값)


string16

card_no

카드번호
반드시 숫자 값만 입력해 주시기 바랍니다.
ex) 44445555666677777


string4

card_expiry

신용카드 유효기간
년월(YYMM) 순서로 입력해 주시기 바랍니다.
ex) 07/23 (MM/YY) 입력시 2307


string10

card_taxno

카드인증정보
생년월일 6자리 or 사업자번호 10자리
※인증방식일 경우 요청


string2

card_pwd

카드 비밀번호
카드 비밀번호 앞 두자리
※인증방식일 경우 요청

API 승인처리 예시

String    target_URL = "https://stg-spl.kcp.co.kr/gw/hub/v1/payment";  		  // 개발서버
JSONObject json_req = new JSONObject();

json_req.put("site_cd", site_cd);
json_req.put("kcp_cert_info", kcp_cert_info);
json_req.put("pay_method", "CARD");
json_req.put("cust_ip", "");
json_req.put("amount", good_mny);
json_req.put("card_mny", good_mny);
json_req.put("currency", currency);
json_req.put("quota", quota);
json_req.put("ordr_idxx", ordr_idxx);
json_req.put("good_name", good_name);
json_req.put("buyr_name", buyr_name);
json_req.put("buyr_mail", buyr_mail);
json_req.put("buyr_tel2", buyr_tel2);
json_req.put("card_tx_type", "11111000");
json_req.put("card_no", card_no);
json_req.put("card_expiry", card_expiry);

String temp_req_data 	= json_req.toString();
String req_data 	= temp_req_data.replace(",",",\r\n");

String inputLine 		= null;
StringBuffer outResult  = new StringBuffer();

try
{
  URL url = new URL(target_URL);
  HttpURLConnection conn = (HttpURLConnection)url.openConnection();
  conn.setDoOutput(true);
  conn.setRequestMethod("POST");
  conn.setRequestProperty("Content-Type", "application/json");
  conn.setRequestProperty("Accept-Charset", "UTF-8");

  OutputStream os = conn.getOutputStream();
  os.write(req_data.getBytes("UTF-8"));
  os.flush();

  BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"));
  while ((inputLine = in.readLine()) != null)
  {
    outResult.append(inputLine);
  }
  conn.disconnect();
}
catch(Exception e)
{
  e.printStackTrace();
}

String temp_result = outResult.toString();
String res_data = temp_result.replace(",",",\r\n");

// RES JSON DATA Parsing
JSONParser parser = new JSONParser();
JSONObject json_res = (JSONObject) parser.parse(temp_result);

String res_cd = (String) json_res.get("res_cd");
String res_msg = (String) json_res.get("res_msg");
	
header("Content-type: text/html; charset=utf-8");

$target_URL = "https://stg-spl.kcp.co.kr/gw/hub/v1/payment"; // 개발서버

// 인증서 정보(직렬화)

$data = array("site_cd" => $site_cd,
      "kcp_cert_info" => $kcp_cert_info,
      "pay_method" => "CARD",
      "cust_ip" => "",
      "amount" => $good_mny,
      "card_mny"  => $good_mny,
      "currency" => $currency,
      "quota" => $quota,
      "ordr_idxx" => $ordr_idxx,
      "good_name" => $good_name,
      "buyr_name" => $buyr_name,
      "buyr_mail" => $buyr_mail,
      "buyr_tel2" => $buyr_tel2,
      "card_tx_type" => "11111000",
      "card_no" => $card_no,
      "card_expiry" => $card_expiry
      );

$req_data = json_encode($data);
$header_data = array( "Content-Type: application/json", "charset=utf-8" );

// API REQ
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $target_URL);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header_data);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $req_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// API RES
$res_data  = curl_exec($ch);

// RES JSON DATA Parsing
$json_res = json_decode($res_data, true);

$res_cd = $json_res["res_cd"];
$res_msg = $json_res["res_msg"];
target_URL = "https://stg-spl.kcp.co.kr/gw/hub/v1/payment"; // 개발서버
req_data = "{\"site_cd\" : \"" + site_cd + "\"," +
            "\"kcp_cert_info\":\"" + KCP_CERT_INFO + "\"," +
            "\"pay_method\":\"" +"CARD" + "\"," +
            "\"cust_ip\":\"" + "" + "\"," +
            "\"amount\":\"" + good_mny + "\"," +
            "\"card_mny\":\"" + good_mny + "\"," +
            "\"currency\":\"" + currency + "\"," +
            "\"quota\":\"" + quota + "\"," +
            "\"ordr_idxx\":\"" + ordr_idxx + "\"," +
            "\"good_name\":\"" + good_name + "\"," +
            "\"buyr_name\":\"" + buyr_name + "\"," +
            "\"buyr_mail\":\"" + buyr_mail + "\"," +
            "\"buyr_tel2\":\"" + buyr_tel2 + "\"," +
            "\"card_tx_type\":\"" + "11121000" + "\"," +
            "\"card_no\":\"" + card_no + "\"," +
            "\"card_expiry\":\"" + card_expiry + "\"," +
            "\"card_taxno\":\"" + card_taxno + "\"," +
            "\"card_pwd\":\"" + card_pwd + "\"}";
// API REQ
HttpWebRequest req = (HttpWebRequest)WebRequest.Create(target_URL);
req.Method = "POST";
req.ContentType = "application/json";

byte[] byte_req = Encoding.UTF8.GetBytes(req_data);
req.ContentLength = byte_req.Length;

Stream st = req.GetRequestStream();
st.Write(byte_req, 0, byte_req.Length);
st.Close();

// API RES
HttpWebResponse res = (HttpWebResponse)req.GetResponse();
StreamReader st_read = new StreamReader(res.GetResponseStream(), Encoding.GetEncoding("utf-8"));
res_data = st_read.ReadToEnd();

st_read.Close();
res.Close();

// RES JSON DATA Parsing
JObject json_data = JObject.Parse(res_data);
res_cd = json_data["res_cd"].ToString();
res_msg = json_data["res_msg"].ToString();
Response.CharSet = "UTF-8"

target_URL = "https://stg-spl.kcp.co.kr/gw/hub/v1/payment" ' 승인요청 API 개발환경

req_data = "{""site_cd"":""" & site_cd & """,""kcp_cert_info"":""" & kcp_cert_info & """,""pay_method"":""" & "CARD" & """,""amount"":""" & good_mny & """,""card_mny"":""" & good_mny & """,""currency"":""" & curr_code & """,""quota"":""" & quota & """,""ordr_idxx"":""" & ordr_idxx & """,""good_name"":""" & good_name & """,""buyr_name"":""" & buyr_name & """,""buyr_mail"":""" & buyr_mail & """,""buyr_tel2"":""" & buyr_tel2 & """,""card_tx_type"":""" & "11121000" & """,""card_no"":""" & card_no & """,""card_expiry"":""" & card_expiry & """,""card_taxno"":""" & card_taxno & """,""card_pwd"":""" & card_pwd & """}"

' API REQ
set req = Server.CreateObject("MSXML2.ServerXMLHTTP")
req.open "POST", target_URL, false
req.setRequestHeader "Content-Type", "application/json;charset=UTF-8"
req.send req_data

' API RES
'요청 성공인 경우
if req.status = 200 then
  res_data = req.ResponseText
'요청 실패인 경우
else
  res_data = "http error code : " & req.status
end if

set req = nothing

'' RES JSON DATA Parsing
set json_data = JSON.parse(res_data)

res_cd = json_data.res_cd
res_msg = json_data.res_msg
// 결제 REQ DATA
var req_data = {
  site_cd : site_cd,
  kcp_cert_info : KCP_CERT_INFO,
  pay_method : "CARD",
  cust_ip : "",
  amount : req.body.good_mny,
  card_mny : req.body.good_mny,
  currency : req.body.currency,
  quota : req.body.quota,
  ordr_idxx : req.body.ordr_idxx,
  good_name : req.body.good_name,
  buyr_name : req.body.buyr_name,
  buyr_mail : req.body.buyr_mail,
  buyr_tel2 : req.body.buyr_tel2,
  card_tx_type : "11121000",
  card_no : req.body.card_no,
  card_expiry : req.body.card_expiry,
  card_taxno : req.body.card_taxno,
  card_pwd : req.body.card_pwd
};

// 결제 API URL
// 개발 : https://stg-spl.kcp.co.kr/gw/hub/v1/payment
// 운영 : https://spl.kcp.co.kr/gw/hub/v1/payment
fetch("https://stg-spl.kcp.co.kr/gw/hub/v1/payment", {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(req_data),
  })
  // 결제 API RES
  .then(response => {
    return response.json();
  })
  .then(data => {
  res.render('kcp_api_page', {
    req_data : JSON.stringify(req_data),
    res_data : JSON.stringify(data),
    data : data,
    ordr_idxx : req.body.ordr_idxx,
    bSucc : bSucc,
    good_name : req.body.good_name,
    buyr_name : req.body.buyr_name,
    buyr_tel2 : req.body.buyr_tel2,
    buyr_mail : req.body.buyr_mail
  });
});
target_URL = 'https://stg-spl.kcp.co.kr/gw/hub/v1/payment' #개발환경
# target_URL = 'https://spl.kcp.co.kr/gw/hub/v1/payment' #운영환경
headers = {'Content-Type': 'application/json', 'charset': 'UTF-8'}
req_data = {
    'site_cd' : site_cd,
    'kcp_cert_info' : kcp_cert_info,
    'ordr_idxx' : ordr_idxx,
    'buyr_name' : buyr_name,
    'good_name' : good_name,
    'buyr_mail' : buyr_mail,
    'buyr_tel2' : buyr_tel2,
    'currency' : currency,
    'amount' : good_mny,
    'card_mny' : good_mny,
    'quota' : quota,
    'pay_method' : "CARD",
    'card_tx_type' : '11121000',
    'card_no' : card_no,
    'card_expiry' : card_expiry,
    'card_taxno' : card_taxno,
    'card_pwd' : card_pwd
}
res = requests.post(target_URL, headers=headers, data=json.dumps(req_data, ensure_ascii=False, indent="\t").encode('utf8'))

승인응답 파라미터 가이드

공통응답 파라미터

승인성공 파라미터


string4

res_cd

결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴


string100

res_msg

결과메세지


string100

res_en_msg

영문 결과 메시지


string14

tno

NHN KCP 거래 고유번호
※ 거래고유번호 전체로 사용 하시기 바랍니다. (임의의 숫자나 파싱하여 사용 불가)


number12

amount

결제 금액
결제 건의 총 결제 금액이 리턴 됩니다.
최종 결제 금액의 처리는 승인완료 후 리턴 데이터 중 amount 로 처리하여야 하며 반드시 업체의 DB금액과 비교하여 검증하시기 바랍니다


승인실패 파라미터


string4

res_cd

결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴


string100

res_msg

결과메세지

승인응답 파라미터

신용카드 결제 응답


string4

card_cd

결제 건의 발급 사 코드


string32

card_name

결제 건의 발급 사 명


string16

card_no

결제 건의 카드번호 (카드번호 16자리 중 3번째구간은 마스킹)


string8

app_no

결제 건의 승인번호


number14

app_time

결제 건의 결제(승인) 시간


string1

noinf

결제 건의 무이자 여부


string4

noinf_type

noinf = Y 일 때 (무이자 결제인 경우)
카드사 이벤트 무이자인 경우 : CARD
상점 부담 무이자인 경우 : SHOP


number12

quota

결제 건의 할부 기간


number12

card_mny

결제 건의 총 결제금액 중 신용카드 결제금액


string4

acqu_cd

매입사코드


string20

acqu_name

매입사명


string1

partcanc_yn

결제 건의 부분취소 가능 유무


number1

card_bin_type_01

결제 건의 카드 구분 정보
개인 : 0 / 법인 : 1


number1

card_bin_type_02

결제 건의 카드 구분 정보
일반 : 0 / 체크 : 1


string4

card_bin_bank_cd

카드발급사 은행코드

승인처리 구성하기

승인처리 페이지 구성시 승인요청 서명데이터생성 망취소 결과처리 로직을 포함 할 수 있습니다.

망취소 로직은 거래취소 페이지를 참고 부탁 드리겠습니다.

서명데이터생성 로직은 참고사항의 서버인증서 페이지를 참고 부탁 드리겠습니다.

결제창 호출, 승인처리를 포함한 전체 샘플이 필요하신 경우 다운로드 자료실을 이용해 주세요.