REST API 전환 방법
KCP 결제 통신 방식이 TCP/IP에서 HTTPS로 변경됨에 따라, ppcli에서 REST API로 전환 작업을 해 주셔야 합니다.
주요 변경 사항은 API URL, 인증 정보, 요청 데이터 세팅입니다. 아래 결제 승인 및 취소 API 전환 방법을 참고해 주세요.
결제 승인 변경 사항
1. API URL
ppcli 모듈 내 승인 요청 URL을 제거한 후, 아래와 같이 새로운 승인 요청 URL을 추가합니다.
- 테스트:
https://stg-spl.kcp.co.kr/gw/enc/v1/payment - 운영:
https://spl.kcp.co.kr/gw/enc/v1/payment
String target_URL = "https://stg-spl.kcp.co.kr/gw/enc/v1/payment";
2. 인증 정보
ppcli 모듈 내 site_key를 제거한 후, 파트너 관리자에서 발급한 서비스 인증서(kcp_cert_info)를 추가합니다.
서비스 인증서와 개인 키는 가맹점 인증을 위해 사용됩니다.
- 파트너 관리자에서 발급한 서비스 인증서와 개인키는 다운로드 폴더에 저장됩니다.
- 다운로드 폴더 경로 : C:\Users\사용자명\Downloads
String kcp_cert_info = "-----BEGIN CERTIFICATE-----MIIDgTCCAmmg...bazMZEyj2O42hw==-----END CERTIFICATE-----";
3. 요청 데이터 세팅
ppcli 라이브러리 객체 대신 JSON 객체에 승인 요청 데이터를 담아 POST 방식으로 전송합니다.
PPCLI(기존 방식)BEFORE
// ppcli 객체 생성 및 통신 환경 초기화 J_PP_CLI_N c_PayPlus = new J_PP_CLI_N(); c_PayPlus.mf_init( "", g_conf_gw_url, g_conf_gw_port, tx_mode, log_dir ); c_PayPlus.mf_init_set(); c_PayPlus.mf_set_enc_data( enc_data, enc_info ); int ordr_data_set_no; ordr_data_set_no = c_PayPlus.mf_add_set( "ordr_data" ); // 결제 검증 파라미터 c_PayPlus.mf_set_us( ordr_data_set_no, "ordr_mony", "1004" ); c_PayPlus.mf_set_us( ordr_data_set_no, "pay_type", "PACA" ); // ppcli 라이브러리로 승인 요청 실행 c_PayPlus.mf_do_tx( site_cd, site_key, tran_cd, "", ordr_idxx, log_level, "0" );
REST API(전환 방식)AFTER
// REST API 요청 JSON 생성 및 필수 파라미터 설정 JSONObject json_req = new JSONObject(); json_req.put("kcp_cert_info", kcp_cert_info); json_req.put("site_cd", site_cd); json_req.put("tran_cd", tran_cd); json_req.put("enc_data", enc_data); json_req.put("enc_info", enc_info); // 결제 검증 파라미터 json_req.put("ordr_mony", "1004"); json_req.put("pay_type", "PACA"); String temp_req_data = json_req.toString(); String req_data = temp_req_data.replace(",",",\r\n"); String inputLine = null; StringBuffer outResult = new StringBuffer(); // HTTPS POST 방식으로 승인 요청 URL url = new URL(target_URL); HttpURLConnection conn = (HttpURLConnection)url.openConnection(); conn.setRequestMethod("POST"); OutputStream os = conn.getOutputStream(); os.write(req_data.getBytes("UTF-8")); os.flush();
+ 응답 데이터 추출
ppcli 라이브러리의 응답 조회 방식 대신 JSON 응답을 파싱하여 값을 추출합니다.
PPCLI(기존 방식)BEFORE
// ppcli 라이브러리에서 응답 값 추출 res_cd = c_PayPlus.m_res_cd; res_msg = c_PayPlus.m_res_msg; pay_method = c_PayPlus.mf_get_res("pay_method"); // 카드 결제 응답 예시 card_cd = c_PayPlus.mf_get_res("card_cd"); card_name = c_PayPlus.mf_get_res("card_name"); app_time = c_PayPlus.mf_get_res("app_time");
REST API(전환 방식)AFTER
// API 응답 데이터를 문자열로 변환 String temp_result = outResult.toString(); // JSON 응답을 파싱하여 값 추출 JSONObject res = (JSONObject) new JSONParser().parse(temp_result); res_cd = (String) res.get("res_cd"); res_msg = (String) res.get("res_msg"); pay_method = (String) res.get("pay_method"); // 카드 결제 응답 예시 card_cd = (String) res.get("card_cd"); card_name = (String) res.get("card_name"); app_time = (String) res.get("app_time");
결제 취소 변경 사항
1. API URL
- 테스트:
https://stg-spl.kcp.co.kr/gw/mod/v1/cancel - 운영:
https://spl.kcp.co.kr/gw/mod/v1/cancel
2. 인증 정보
ppcli 모듈 내 site_key를 제거한 후, 파트너 관리자에서 발급한 서비스 인증서(kcp_cert_info)를 추가합니다.
서비스 인증서와 개인 키는 가맹점 인증을 위해 사용됩니다.
String kcp_cert_info = "-----BEGIN CERTIFICATE-----MIIDgTCCAmmg...bazMZEyj2O42hw==-----END CERTIFICATE-----";
3. 서명데이터 생성
서명데이터(kcp_sign_data)는 가맹점 부인 방지와 요청 데이터의 무결성 검증을 위한 데이터입니다.kcp_sign_data = site_cd + "^" + tno + "^" + mod_type 규칙으로 원문을 조합한 뒤, 개인키로 SHA256withRSA 서명을 생성하고 Base64로 인코딩하여 전달합니다.
코드 예시(JSP)
아래는 Java(JSP) 환경에서 서명데이터를 생성하는 예시입니다.
서명데이터 생성JSP
// 개인 키 경로 및 비밀번호 String filePath = "C:/.../certificate/splPrikeyPKCS8.pem"; String privateKeyPassword = "changeit"; // 서명데이터 생성 public static String makeSignatureData(String targetData){ String signData = null; PrivateKey priKey = null; priKey = loadSplMctPrivateKeyPKCS8(); byte[] btArrTargetData = targetData.getBytes( StandardCharsets.UTF_8 ); try { Signature sign = Signature.getInstance( "SHA256WithRSA" ); sign.initSign( priKey ); sign.update( btArrTargetData ); byte[] btArrSignData = sign.sign(); signData = Base64.getEncoder().encodeToString( btArrSignData ); } catch (NoSuchAlgorithmException e) { e.printStackTrace(); } catch (InvalidKeyException e) { e.printStackTrace(); } catch (SignatureException e) { e.printStackTrace(); } return signData; } // 서명데이터 생성 호출 String cancel_target_data = site_cd + "^" + tno + "^" + mod_type; String kcp_sign_data = makeSignatureData(cancel_target_data);
4. 요청 데이터 세팅
ppcli 라이브러리 객체 대신 JSON 객체에 취소 요청 데이터를 담아 POST 방식으로 전송합니다.
PPCLI(기존 방식)BEFORE
// ppcli 객체 생성 및 통신 환경 초기화 J_PP_CLI_N c_PayPlus = new J_PP_CLI_N(); c_PayPlus.mf_init( "", g_conf_gw_url, g_conf_gw_port, g_conf_tx_mode, g_conf_log_path ); c_PayPlus.mf_init_set(); int mod_data_set_no; mod_data_set_no = c_PayPlus.mf_add_set( "mod_data" ); c_PayPlus.mf_set_us( mod_data_set_no, "tno" , tno ); c_PayPlus.mf_set_us( mod_data_set_no, "mod_type", mod_type ); c_PayPlus.mf_set_us( mod_data_set_no, "mod_desc", mod_desc ); c_PayPlus.mf_set_us( mod_data_set_no, "mod_ip" , mod_ip ); if ( mod_type.equals( "STPC" ) ) { c_PayPlus.mf_set_us( mod_data_set_no, "mod_mny", mod_mny ); c_PayPlus.mf_set_us( mod_data_set_no, "rem_mny", rem_mny ); } // ppcli 라이브러리로 승인 요청 실행 c_PayPlus.mf_do_tx( g_conf_site_cd, g_conf_site_key, tran_cd, mod_ip, "", g_conf_log_level, "0" );
REST API(전환 방식)AFTER
// REST API 요청 JSON 생성 및 필수 파라미터 설정 JSONObject json_req = new JSONObject(); json_req.put("kcp_cert_info", kcp_cert_info ); json_req.put("site_cd" , site_cd ); json_req.put("mod_type" , mod_type ); json_req.put("mod_ip" , mod_ip ); json_req.put("tno" , tno ); json_req.put("mod_desc" , mod_desc ); json_req.put("kcp_sign_data", kcp_sign_data ); if (mod_type.equals("STPC")) { json_req.put("mod_mny", mod_mny ); json_req.put("rem_mny", rem_mny ); } String req_data = json_req.toString(); String inputLine = null; StringBuffer outResult = new StringBuffer(); // HTTPS POST 방식으로 취소 요청 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();