수기결제 연동하기
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 서비스 인증서 관련 상세 내용은 서버 인증서 페이지를 참고 부탁 드립니다.
승인요청 파라미터 가이드
승인요청 파라미터
site_cd
KCP발급 사이트(상점)코드
가입 시 발송해드리는 연동메일 참조 / 테스트코드 : T0000
kcp_cert_info
KCP 인증서정보(직렬화)
관리자 페이지에서 발급받은 인증서 정보(직렬화 하여 요청)
pay_method
결제수단
CARD : 고정값
cust_ip
요청자IP
amount
총 결제금액
결제금액은 숫자 이외의 문자(콤마 등)는 허용하지 않습니다
ex) 1004
card_mny
카드 결제금액
결제금액은 숫자 이외의 문자(콤마 등)는 허용하지 않습니다
ex) 1004
currency
화폐단위
※ 원화 - WON : 410 / 달러 - USD : 840
quota
할부개월 수
할부결제 시에 사용할 할부 개월을 입력하는 변수로 반드시 두 자리의 숫자 값으로 입력해주시기 바랍니다.
ex) 5개월의 경우 "05"로 설정
ordr_idxx
가맹점에서 자체 생성한 주문번호
가맹점에서 주문 정보를 관리하기 위해 자체 생성한 주문번호를 이 변수에 입력해 주시기 바랍니다.
ex) TEST1235467890
good_name
상품명
상품의 정보를 간략하게 입력하여 주시기 바랍니다.
※ 필수 정보는 아니지만 고객 안내 및 주문정보 관리를 위하여 정확한 상품명을 넘겨야 합니다.
buyr_name
주문자 명
ex) 홍길동
buyr_mail
주문자 E-Mail
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.
buyr_tel2
주문자 휴대폰번호
('-' 사용 무관)
card_tx_type
카드 전문 유형
11121000 : 인증방식(고정값)
11111000 : 비인증방식(고정값)
card_no
카드번호
반드시 숫자 값만 입력해 주시기 바랍니다.
ex) 44445555666677777
card_expiry
신용카드 유효기간
년월(YYMM) 순서로 입력해 주시기 바랍니다.
ex) 07/23 (MM/YY) 입력시 2307
card_taxno
카드인증정보
생년월일 6자리 or 사업자번호 10자리
※인증방식일 경우 요청
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'))
승인응답 파라미터 가이드
공통응답 파라미터
승인성공 파라미터
res_cd
결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴
res_msg
결과메세지
res_en_msg
영문 결과 메시지
tno
NHN KCP 거래 고유번호
※ 거래고유번호 전체로 사용 하시기 바랍니다.
(임의의 숫자나 파싱하여 사용 불가)
amount
결제 금액
결제 건의 총 결제 금액이 리턴 됩니다.
최종 결제 금액의 처리는 승인완료 후 리턴 데이터 중 amount 로 처리하여야 하며 반드시 업체의 DB금액과 비교하여 검증하시기 바랍니다
승인실패 파라미터
res_cd
결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴
res_msg
결과메세지
승인응답 파라미터
신용카드 결제 응답
card_cd
결제 건의 발급 사 코드
card_name
결제 건의 발급 사 명
card_no
결제 건의 카드번호 (카드번호 16자리 중 3번째구간은 마스킹)
app_no
결제 건의 승인번호
app_time
결제 건의 결제(승인) 시간
noinf
결제 건의 무이자 여부
noinf_type
noinf = Y 일 때 (무이자 결제인 경우)
카드사 이벤트 무이자인 경우 : CARD
상점 부담 무이자인 경우 : SHOP
quota
결제 건의 할부 기간
card_mny
결제 건의 총 결제금액 중 신용카드 결제금액
acqu_cd
매입사코드
acqu_name
매입사명
partcanc_yn
결제 건의 부분취소 가능 유무
card_bin_type_01
결제 건의 카드 구분 정보
개인 : 0 / 법인 : 1
card_bin_type_02
결제 건의 카드 구분 정보
일반 : 0 / 체크 : 1
card_bin_bank_cd
카드발급사 은행코드
승인처리 구성하기
승인처리 페이지 구성시 승인요청 서명데이터생성 망취소 결과처리 로직을 포함 할 수 있습니다.
망취소 로직은 거래취소 페이지를 참고 부탁 드리겠습니다.
서명데이터생성 로직은 참고사항의 서버인증서 페이지를 참고 부탁 드리겠습니다.
결제창 호출, 승인처리를 포함한 전체 샘플이 필요하신 경우 다운로드 자료실을 이용해 주세요.