거래조회


조회요청

거래조회 에서는 상점에서 NHNKCP의 거래 상태를 조회하는 방법에 대해 설명합니다.

조회데이터를 API URL로 승인요청 하세요.

API Request

<!-- API 호출 -->

1https://spl.kcp.co.kr/std/inquery

테스트 환경 : https://stg-spl.kcp.co.kr/std/inquery


서비스 인증서

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

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

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


kcp_sign_data

kcp_sign_data 는거래조회 거래취소 시에 필요합니다.

kcp_sign_data는 생성시개인키(PRIVATE KEY) 가 필요하며 테스트 개인키는 다운로드 자료실을 확인해주세요.

kcp_sign_data 생성예시

public class MakeSplParam
  {
    static{ Security.addProvider( new BouncyCastleProvider() ); }

      public static void main(String[] args)
      {
          PrivateKey priKey       = loadSplMctPrivateKeyPKCS8( "../splPrikeyPKCS8.pem", "changeit" ); // (개인키 경로, 개인키 비밀번호)
          String signData   = makeSignatureData( priKey, "T0000^20210719000000^PACA" );	// 서명데이터 생성
          System.out.println( "\n[서명데이터(kcp_sign_data)] : " + signData );
      }
      public static PrivateKey loadSplMctPrivateKeyPKCS8( String filePath, String privateKeyPassword )
      {
          PrivateKey priKey = null;
      Path path = Paths.get( filePath );
      String strPriKeyData = Files.readAllLines( path )
          .stream()
          .filter( line -> !line.startsWith( "-----BEGIN" ) && !line.startsWith( "-----END" ) )
          .collect( Collectors.joining() );

      byte[] btArrPriKey   = Base64.getDecoder().decode( strPriKeyData );

      ASN1Sequence derSeq = ASN1Sequence.getInstance( btArrPriKey );
      PKCS8EncryptedPrivateKeyInfo encPkcs8PriKeyInfo = new PKCS8EncryptedPrivateKeyInfo( org.bouncycastle.asn1.pkcs.EncryptedPrivateKeyInfo.getInstance( derSeq ) );
      JcaPEMKeyConverter pemKeyConverter = new JcaPEMKeyConverter();
      InputDecryptorProvider decProvider = new JceOpenSSLPKCS8DecryptorProviderBuilder().build( privateKeyPassword.toCharArray() );
      PrivateKeyInfo priKeyInfo          = encPkcs8PriKeyInfo.decryptPrivateKeyInfo( decProvider );
      priKey                             = pemKeyConverter.getPrivateKey( priKeyInfo );

          return priKey;
      }
      public static String makeSignatureData(PrivateKey priKey, String targetData)
      {
          String signData = null;
          byte[] btArrTargetData = targetData.getBytes( StandardCharsets.UTF_8 );

      Signature sign = Signature.getInstance( "SHA256WithRSA" );
      sign.initSign( priKey );
      sign.update( btArrTargetData );

      byte[] btArrSignData = sign.sign();
      signData = Base64.getEncoder().encodeToString( btArrSignData );

      return signData;
      }
  }
<?php
  $cancel_target_data = "T0000^22284971100001^STSC";
  // 결제 취소 (cancel) = site_cd^KCP거래번호^취소유형

  $key_data = file_get_contents('../splPrikeyPKCS8.pem');
  // 개인키 경로 ("splPrikeyPKCS8.pem" 은 테스트용 개인키)
  $pri_key = openssl_pkey_get_private($key_data,'changeit');
  // 개인키 비밀번호

  openssl_sign($cancel_target_data, $signature, $pri_key, 'sha256WithRSAEncryption');
  // 결제 취소 signature 생성
  echo "cancel_signature :".base64_encode($signature)."<br><br>";
?>
namespace kcp_sign_data_sample
{
    class Program
    {
        static void Main(string[] args)
        {
            // PKCS#8 PEM READ
            StreamReader sr = new StreamReader("../splPrikeyPKCS8.pem"); // 개인키 경로 ("splPrikeyPKCS8.pem" 은 테스트용 개인키)
            String privateKeyText = sr.ReadToEnd();
            // 개인키 비밀번호
            string privateKeyPass = "changeit"; // 개인키 비밀번호 ("changeit" 은 테스트용 개인키 비밀번호)
            // 개인키정보 READ
            StringReader stringReader = new StringReader(privateKeyText);
            PemReader pemReader = new PemReader(stringReader, new PasswordFinder(privateKeyPass));
            RsaPrivateCrtKeyParameters keyParams = (RsaPrivateCrtKeyParameters)pemReader.ReadObject();

            byte[] tmpSource = Encoding.ASCII.GetBytes("T0000^22671971380028^PACA");

            ISigner sign = SignerUtilities.GetSigner(PkcsObjectIdentifiers.Sha256WithRsaEncryption.Id);
            sign.Init(true, keyParams);
            sign.BlockUpdate(tmpSource, 0, tmpSource.Length);

            var kcp_sign_data = sign.GenerateSignature();
            // Console 출력
            Console.WriteLine("kcp_sign_data:" + Convert.ToBase64String(kcp_sign_data));
            Console.ReadKey();
        }

        private class PasswordFinder : IPasswordFinder
        {
            private string password;
            public PasswordFinder(string pwd)
            {
              password = pwd;
            }
            public char[] GetPassword()
            {
              return password.ToCharArray();
            }
        }
    }
}
<%
    textToSign = "T0000^22671971380028^PACA" '서명대상데이터(site_cd^tno^mod_type)
    set kcpSign = server.createobject("kcp_sign_data_lib.GenSign") '서명데이터생성 예제 lib
    kcp_sign_data = kcpSign.Sign("../splPrikeyPKCS8.pem", "changeit", textToSign) '(테스트용 개인키,테스트용 개인키 비밀번호)

    response.write "kcp_sign_data : " + kcp_sign_data + "<br/>"
%>

  const data = "T0000^22296971511092^PACA";
  const crypto = require('crypto');
  const fs = require('fs');
  // 서명데이터 생성 함수 호출
  const signature = getSignatureToVerify(data);
  // 서명데이터 생성을 위한 개인키 READ
  function getPrivateKeySomehow()
  {
      const pKey = fs.readFileSync('../splPrikeyPKCS8.pem', 'utf8' ); // "splPrikeyPKCS8.pem" 은 테스트용 개인키
      const pKeyObj = crypto.createPrivateKey({
          key : pKey,
          passphrase : "changeit", // "changeit" 은 테스트용 개인키 비밀번호
          format : "pem",
          type : "pkcs8"
          })
      const pKeyStr = pKeyObj.export({
           format: 'pem',
            type: 'pkcs8'
          }).toString();
      return pKeyStr;
  }

  // 서명데이터 생성 함수
  function getSignatureToVerify(data)
  {
      const privateKey = getPrivateKeySomehow();
      const sign = crypto.createSign("SHA256");
      sign.update(data);
      const signature = sign.sign(privateKey, "base64");
      console.log(">>> Signature:\n\n" + signature);
      return signature;
  }

  import OpenSSL
  from OpenSSL import crypto
  import base64

  data = 'T0000^22671971380028^PACA'
  # "splPrikeyPKCS8.pem" 은 테스트용 개인키
  key_file = open('../splPrikeyPKCS8.pem', 'r')
  key = key_file.read()
  key_file.close()
  # "changeit" 은 테스트용 개인키비밀번호
  password = 'changeit'.encode('utf-8')
  pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key, password)
  # 서명데이터생성
  sign = OpenSSL.crypto.sign(pkey, data, 'sha256')
  kcp_sign_data = base64.b64encode(sign)
  print("kcp_sign_data : ", kcp_sign_data)

조회요청 파라미터 가이드

요청 파라미터

string5

site_cd

KCP발급 사이트(상점)코드
테스트코드 : T0000


string40

mod_ordr_idxx

상점 주문번호
※ 주문번호를 조회키로 요청할 경우 전달하는 값입니다.(원거래의 주문번호)
※ KCP거래번호(tno)를 조회키로 요청할 경우 주문번호는 전달하지 않아도 됩니다.


string14

tno

NHN KCP 거래 고유번호
※ KCP거래번호(tno)를 조회키로 요청할 경우 승인결과로 리턴 받으셨던 tno 정보를 전달해주셔야 합니다.
※주문번호를 조회키로 요청하시는 경우 원거래 건의 승인일자를 “YYYYMMDD+000000(숫자 0)” 형식으로 전달해 주시기 바랍니다.


string4

pay_type

조회요청 결제수단
신용카드 = PACA
계좌 = PABK
가상계좌 = PAVC
휴대폰 = PAMC
상품권 = PATK
SSG머니 = PASG
카카오머니 = PAKM
네이버페이포인트 = PANP
엘포인트 = PALP


string가변

kcp_cert_info

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


string가변

kcp_sign_data

KCP 암호화데이터
site_cd + "^" + tno + "^" + pay_type

거래번호 조회 예시

<!-- KCP 거래번호 조회요청 데이터 -->

1<!-- 조회요청 데이터 -->
2{
3 "site_cd":"T0000",
4 "kcp_cert_info":"-----BEGIN CERTIFICATE-----MIID3DCCAsSgAwIBAgIJAMzLXkRXpY3KMA0GCSqGSIb3DQEBCwU...bpE1aPTjDDQsuUduNaCu1jYuBALO+LelrFA...VNeequGLUZSx1il+tJU=-----END CERTIFICATE-----",
5 "kcp_sign_data":"QdwMF6y3GU1JTVkSv7Yn20CCCTeFrKkjvrdZOjShiFibFo...cA0nyX+4HEUZ4Fy3U+htmkZqAfJljeujC1KAL5Flnzqbp5Tst5p5SvZ...0qH7NSq0c6BpedDZb04w==",
6 "pay_type":"PACA",
7 "tno":"2099123112345"
8}

<!-- KCP 주문번호 조회요청 데이터 -->

1<!-- 조회요청 데이터 -->
2{
3 "site_cd":"T0000"",
4 "kcp_cert_info":"-----BEGIN CERTIFICATE-----MIID3DCCAsSgAwIBAgIJAMzLXkRXpY3KMA0GCSqGSIb3DQEBCwU...bpE1aPTjDDQsuUduNaCu1jYuBALO+LelrFA...VNeequGLUZSx1il+tJU=-----END CERTIFICATE-----",
5 "kcp_sign_data":"QdwMF6y3GU1JTVkSv7Yn20CCCTeFrKkjvrdZOjShiFibFo...cA0nyX+4HEUZ4Fy3U+htmkZqAfJljeujC1KAL5Flnzqbp5Tst5p5SvZ...0qH7NSq0c6BpedDZb04w==",
6 "pay_type":"PACA",
7 "mod_ordr_idxx":"kcp12345",
8 "tno":"20210721000000"
9}

Json String 전송 / 조회 응답 값은 동일한 Json 형태로 리턴됩니다.


조회결과 파라미터 가이드

공통 파라미터

string4

res_cd

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


string100

res_msg

결과메세지


string100

res_en_msg

영문 결과 메시지


string14

tno

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


string20

shop_status

거래건의 정산 상태

응답 파라미터

신용카드응답


number12

amount

총 결제 금액


string4

card_cd

결제 건의 발급 사 코드


string32

card_name

결제 건의 발급 카드사 명


string20

bizx_numb

결제건의 가맹점번호
(NHN KCP 대행인 경우 카드사 - NHN KCP 가맹점 번호가 리턴)


string8

app_no

결제 건의 승인번호


string14

app_time

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


string1

noinf

결제 건의 무이자 여부


string1

canc_card_yn

취소상태
Y(취소) / N(승인, 부분취소)


number2

quota

결제 건의 할부 기간


number12

card_mny

결제 건의 총 결제금액 중 신용카드 결제금액
만약 총 결제금액(amount) 10000 원 중 쿠폰할인 2000 원 받았다면 card_mny=8000 이 됩니다.
*페이코 포인트, 쿠폰 100% 결제 시 card_mny=0 으로 리턴될 수 있으니 반드시 총 결제 금액 처리는 amount 금액으로 체크하시기 바랍니다.


number12

coupon_mny

결제 건의 무이자 여부결제 건의 쿠폰 할인, 페이코 포인트 사용 금액
결제 건의 쿠폰 할인 금액 또는 페이코 포인트 사용 금액이 리턴됩니다.
만약 총 결제금액(amount) 10000 원 중 쿠폰 할인을 2000 원 받았다면 coupon_mny=2000 이 됩니다.


partcanc_yn1

app_no

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


string16

card_no

결제건의 카드번호(마스킹)


string1

escw_yn

결제건의 에스크로 여부


string14

can_time

취소시간
shop_status(거래상태) 값이 STSC(취소)만 리턴


string12

rem_mny

결제건의 남은 금액


string12

card_rem_mny

카드 남은 금액


string12

stat_ca_cd

최종결제상태


string4

van_cd

승인VAN사
Ex)VNKC


string4

van_status

VAN결제상태


string4

acqu_cd

매입사코드


string20

acqu_name

매입사명


string4

tax_flag

과세유형
TG01:과세
TG02:비과세
TG03:복합과세


number12

coupon_rem_mny

쿠폰 남은 금액


number10

mall_taxno

가맹점 사업자번호


계좌이체응답


number12

amount

계좌이체 결제건의 이체금액


string14

tno

KCP거래번호


number12

bk_mny

계좌이체 결제건의 이체금액


string4

bk_code

계좌이체 결제건의 은행코드


string1

escw_yn

결제건의 에스크로 여부


string20

bk_name

계좌이체 결제건의 은행명


string14

app_time

계좌이체 결제시각


string1

bk_reciept_gubn

계좌이체 결제건의 현금영수증 등록여부


string7

bk_tid

계좌이체 승인번호


string1

canc_bk_yn

계좌이체 취소 가능여부


number12

bk_rem_mny

계좌이체 남은금액


string4)

stat_bk_cd

최종결제상태


string4

shop_status

거래 건 정산상태


가상계좌응답


number21

amount

가상계좌 채번금액


string20

bankname

결제 건의 은행 명


string4

bankcode

조회대상의 가상계좌 입금코드


string20

account

조회대상의 가상계좌 번호


string14

va_date

가상계좌 입금마감일


string1

escw_yn

결제건의 에스크로 여부


number12

ipkum_money

가상계좌 입금금액


string14

app_time

조회 대상 거래건의 입금 시각


string40

van_txid

조회대상의 가상계좌 중계기관ID


string1

va_reciept_gubn

가상계좌 현금영수증 등록여부


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


string1

va_tr_code

현금영수증 발행용도 (소득공제 - 0, 지출증빙 - 1)


휴대폰 결제응답


number12

amount

휴대폰 결제 금액


string14

tno

KCP거래번호


string4

van_code

조회대상의 휴대폰 결제 기관코드


string3

commid

조회대상의 휴대폰 통신사


string16

mobile_no

결제 건의 휴대폰 번호


string14

app_time

휴대폰 결제시각


number12

hp_mny

조회대상의 휴대폰 결제 금액


string4

stat_hp_cd

최종결제상태


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


상품권 결제응답


number12

amount

휴대폰 결제 금액


string14

tno

KCP거래번호


string4

tk_van_code

조회대상 상품권사 코드


string20

tk_app_no

조회대상 상품권 승인번호


string14

tk_app_time

조회대상 상품권 승인시각


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


SSG머니 결제응답


string14

tno

KCP거래번호


string14

app_ssgmny_time

간편결제 승인시각


string14

service_corp_id

기관코드


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


카카오머니 결제응답


number12

kakaomny_mny

카카오머니 결제금액


string14

tno

KCP거래번호


string14

app_kakaomny_time

간편결제 승인시각


string4

service_corp_id

기관코드


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


네이버페이 포인트 결제응답


number12

naverpoint_mny

결제금액


string14

tno

KCP거래번호


string14

app_easypoint_time

간편결제 승인시각


string4

service_corp_id

기관코드


string14

app_cash_receipt_no

현금영수증 거래번호


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태


엘포인트 결제응답


number12

lpoint_mny

결제금액


string14

tno

KCP거래번호


string14

app_easypoint_time

간편결제 승인시각


string4

service_corp_id

기관코드


string4

shop_status

거래 건 정산상태


string4

van_status

VAN결제상태