Inquery


Request Query

Transaction query section describes how a merchant requests transaction to be queried.

Request Authorization of Query data with API URL.

API Request

<!-- API Call -->

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

Test : https://stg-spl.kcp.co.kr/std/inquery


Server Certificate

Extraction of data values from NHN KCP issued certificate,
For Merchant authentication, the certificate information issued by KCP must be delivered in text format.
The text value within the certificate must be serialized and delivered as the value of kcp_cert_info.

the parameter kcp_cert_info is needed for requesting Authorization cancel(mod) trade registration inquery


kcp_sign_data

Below codes for processing authorization is included in the auto-cancel logic and,

kcp_sign_data is required for transaction query and cancel request.

To create kcp_sign_data private key is required. For test server private key refer to download menu.

kcp_sign_data example

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

    private static final String PRIVATE_KEY        	= "../splPrikeyPKCS8.pem";
    private static final String PRIVATE_KEY_PASSWD 	= "changeit";
    private static final String ORG_SIGN_DATA 		= "T0000^20210719000000^PACA";
    private static final String SIGNATURE_ALGORITHM = "SHA256WithRSA";

    public static void main(String[] args)
    {

        PrivateKey priKey       = loadSplMctPrivateKeyPKCS8( PRIVATE_KEY, PRIVATE_KEY_PASSWD );

        String signData   = makeSignatureData( priKey, ORG_SIGN_DATA );

        System.out.println( "\n[signdata(kcp_sign_data)] : " );
        System.out.println( signData );
        System.out.println( "-----------------------------\n" );

    }

    public static PrivateKey loadSplMctPrivateKeyPKCS8( String filePath, String privateKeyPassword )
    {
        PrivateKey priKey = null;

        try
        {
            Path path = Paths.get( filePath );

            String strPriKeyData = Files.readAllLines( path )
                    .stream()
                    .filter( line -> !line.startsWith( "-----BEGIN" ) && !line.startsWith( "-----END" ) )
                    .collect( Collectors.joining() );

            // Base64 decoding
            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 );

        }
        catch (IOException e)
        {
            e.printStackTrace();
        }
        catch (OperatorCreationException e)
        {
            e.printStackTrace();
        }
        catch (PKCSException e)
        {
            e.printStackTrace();
        }

        return priKey;
    }

    public static String makeSignatureData(PrivateKey priKey, String targetData)
    {
        String signData = null;

        byte[] btArrTargetData = targetData.getBytes( StandardCharsets.UTF_8 );

        try {
            Signature sign = Signature.getInstance( SIGNATURE_ALGORITHM );
            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;
    }

}
<?php
  $cancel_target_data = "T0000^22284971100001^STSC";
  echo "cancel_target_data : ".$cancel_target_data."<br><br>";

  $inquery_target_data = "T0000^22284971100001^PACA";
  echo "inquery_target_data : ".$inquery_target_data."<br><br>";

  $key_data = file_get_contents('../splPrikeyPKCS8.pem');

  $pri_key = openssl_pkey_get_private($key_data,'changeit');

  openssl_sign($cancel_target_data, $signature, $pri_key, 'sha256WithRSAEncryption');
  echo "cancel_signature :".base64_encode($signature)."<br><br>";

  openssl_sign($inquery_target_data, $signature, $pri_key, 'sha256WithRSAEncryption');
  echo "inquery_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");
          String privateKeyText = sr.ReadToEnd();

          string privateKeyPass = "changeit";

          StringReader stringReader = new StringReader(privateKeyText);
          PemReader pemReader = new PemReader(stringReader, new PasswordFinder(privateKeyPass));
          RsaPrivateCrtKeyParameters keyParams = (RsaPrivateCrtKeyParameters)pemReader.ReadObject();

          var textToSign = "T0000^22671971380028^PACA";

          byte[] tmpSource = Encoding.ASCII.GetBytes(textToSign);

          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();
          }
      }
  }
}
<%
KeyPath = "../splPrikeyPKCS8.pem"
KeyPw	= "changeit"

textToSign = "T0000^22671971380028^PACA"
set kcpSign = server.createobject("kcp_sign_data_lib.GenSign")
kcp_sign_data = kcpSign.Sign(KeyPath, KeyPw, textToSign)

response.write "original: " + textToSign + "<br/>"
response.write "kcp_sign_data : " + kcp_sign_data + "<br/>"
%>
// Inquery
const data = "T0000^22296971511092^PACA";
console.log('\n>>> Message:\n\n' + data);


// crypto Set
const crypto = require('crypto');
const fs = require('fs');
const ALGORITHM = "RSA-SHA256";
const SIGNATURE_FORMAT = "base64";

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(ALGORITHM);
    sign.update(data);
    const signature = sign.sign(privateKey, SIGNATURE_FORMAT);
    console.log(">>> Signature:\n\n" + signature);
    return signature;
}

import OpenSSL
from OpenSSL import crypto
import base64
data = 'T0000^22671971380028^PACA'

# READ
# "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)

Query Request Parameter

Query Parameter

string5

site_cd

Merchant ID


string40

mod_ordr_idxx

Merchant Order Number


string14

tno

transaction number


string4

pay_type

Payment Method
Credit Card = PACA
Bank Transfer = PABK
Virtual Account = PAVC
Mobile Billing = PAMC


stringvar

kcp_cert_info

Serialized KCP Server Certificate


stringvar

kcp_sign_data

Signature Data
site_cd + "^" + tno + "^" + pay_type

Query Request Example

<!-- KCP transaction number(tno) Query Data -->

1<!-- Query Data -->
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}

<!-- mod_ordr_idxx Query Data-->

1<!-- Query Data -->
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}

Response is returned in the same form of Json


Query Response Parameter

Common Parameter


string4

res_cd

Result code


string100

res_msg

Result message


string100

res_en_msg

Result message in English


string14

tno

transaction number


string20

shop_status

Transaction Settlement Status

Credit Card Query Response Parameters

Credit Card Query Response


number12

amount

Payment Amount


string4

card_cd

The issuer code


string32

card_name

The name of the issuer


string20

bizx_numb

Merchant number for the transaction


string8

app_no

The authorization number for the transaction


string14

app_time

The time of payment (approval)


string1

noinf

No-interest option for the transaction. (Y/N)


string1

canc_card_yn

Cancel Status
Y(Cancelled)/N (Approved, Partial Cancelled)


number2

quota

Installment period.


number12

card_mny

Credit card portion of the payment amount


number12

coupon_mny

The coupon discount amount or the payment amount using PAYCO Point will be returned.


partcanc_yn1

app_no

A partial refund availability indicator.


string16

card_no

The card number used for the transaction


string1

escw_yn

Use of Escrow (Y/N)


string14

can_time

The time of cancel
Only when shop_status=STSC


string12

rem_mny

Remaining amount for the transaction


string12

card_rem_mny

Remaining amount for the card


string12

stat_ca_cd

The final status of the transaction


string4

van_cd

VAN code for the transaction


string4

van_status

VAN status for the transaction


string4

acqu_cd

The acquirer code


string20

acqu_name

The name of the acquirer


number12

coupon_rem_mny

Remaining amount for the coupon


number10

mall_taxno

Merchant Business number


Bank Transfer Query Response Parameters


number12

amount

Payment Amount


string14

tno

transaction number


number12

bk_mny

bk_mny


string4

bk_code

The bank code


string1

escw_yn

Use of Escrow


string20

bk_name

The name of bank used


string14

app_time

The time of payment (approval)


string1

bk_reciept_gubn

Cash Receipt registration for the transaction (Y/N)


string7

bk_tid

NHN KCP UNIQUE ID for the transaction


string1

canc_bk_yn

A refund availability indicator.


number12

bk_rem_mny

rem_mn


string4)

stat_bk_cd

The final status of the transaction


string4

shop_status

Transaction Settlement Status


Virtual Account Query Response Parameters


number21

amount

The payment amount for the transaction


string20

bankname

The name of bank used


string4

bankcode

The bank code


string20

account

Virtual Account number for the transaction


string14

va_date

Virtual Account deposit due date for the transaction


string1

escw_yn

Use of Escrow (Y/N)


number12

ipkum_money

The actual deposited amount for the transaction


string14

app_time

The time of issuance of Virtual Account


string40

van_txid

NHN KCP UNIQUE ID for the transaction


string1

va_reciept_gubn

Cash Receipt registration classification


string4

shop_status

Transaction Settlement Status


string4

van_status

VAN Payment status


string1

va_tr_code

Cash Receipt use classification(Income Tax Deduction,
va_tr_code=0 / Evidence of Expense, va_tr_code=1)


Mobile Billing Query Response Parameters


number12

amount

The payment amount for the transaction


string14

tno

transaction number


string4

van_code

Mobile Payment Issuer (Carrier) Code


string3

commid

The Mobile Carrier code


string16

mobile_no

Mobile number for the transaction


string14

app_time

The time of issuance of mobile billing


number12

hp_mny

The payment amount for the transaction


string4

stat_hp_cd

The final status of the transaction


string4

shop_status

Transaction Settlement Status


string4

van_status

VAN Payment status


Voucher Payment Query Response Parameters


number12

amount

The payment amount for the transaction


string14

tno

transaction number


string4

tk_van_code

Voucher company code


string20

tk_app_no

Voucher authorization number


string14

tk_app_time

The time of payment using voucher


string4

shop_status

Transaction Settlement Status


string4

van_status

VAN Payment status


Kakao Money Query Response Parameters


number12

kakaomny_mny

The payment amount for the transaction


string14

tno

transaction number


string14

app_kakaomny_time

The time of issuance of eWallets


string4

service_corp_id

KakaoMoney company code


string4

shop_status

Transaction Settlement Status


string4

van_status

VAN Payment status


NaverPay Point Query Response Parameters


number12

naverpoint_mny

The payment amount for the transaction


string14

tno

transaction number


string14

app_easypoint_time

The time of issuance of eWallets


string4

service_corp_id

NaverPay company code


string14

app_cash_receipt_no

The Cash Receipt Transaction Number


string4

shop_status

Transaction Settlement Status


string4

van_status

VAN Payment status