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
site_cd
Merchant ID
mod_ordr_idxx
Merchant Order Number
tno
transaction number
pay_type
Payment Method
Credit Card = PACA
Bank Transfer = PABK
Virtual Account = PAVC
Mobile Billing = PAMC
kcp_cert_info
Serialized KCP Server Certificate
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
res_cd
Result code
res_msg
Result message
res_en_msg
Result message in English
tno
transaction number
shop_status
Transaction Settlement Status
Credit Card Query Response Parameters
Credit Card Query Response
amount
Payment Amount
card_cd
The issuer code
card_name
The name of the issuer
bizx_numb
Merchant number for the transaction
app_no
The authorization number for the transaction
app_time
The time of payment (approval)
noinf
No-interest option for the transaction. (Y/N)
canc_card_yn
Cancel Status
Y(Cancelled)/N (Approved, Partial Cancelled)
quota
Installment period.
card_mny
Credit card portion of the payment amount
coupon_mny
The coupon discount amount or the payment amount using PAYCO Point will be returned.
app_no
A partial refund availability indicator.
card_no
The card number used for the transaction
escw_yn
Use of Escrow (Y/N)
can_time
The time of cancel
Only when shop_status=STSC
rem_mny
Remaining amount for the transaction
card_rem_mny
Remaining amount for the card
stat_ca_cd
The final status of the transaction
van_cd
VAN code for the transaction
van_status
VAN status for the transaction
acqu_cd
The acquirer code
acqu_name
The name of the acquirer
coupon_rem_mny
Remaining amount for the coupon
mall_taxno
Merchant Business number
Bank Transfer Query Response Parameters
amount
Payment Amount
tno
transaction number
bk_mny
bk_mny
bk_code
The bank code
escw_yn
Use of Escrow
bk_name
The name of bank used
app_time
The time of payment (approval)
bk_reciept_gubn
Cash Receipt registration for the transaction (Y/N)
bk_tid
NHN KCP UNIQUE ID for the transaction
canc_bk_yn
A refund availability indicator.
bk_rem_mny
rem_mn
stat_bk_cd
The final status of the transaction
shop_status
Transaction Settlement Status
Virtual Account Query Response Parameters
amount
The payment amount for the transaction
bankname
The name of bank used
bankcode
The bank code
account
Virtual Account number for the transaction
va_date
Virtual Account deposit due date for the transaction
escw_yn
Use of Escrow (Y/N)
ipkum_money
The actual deposited amount for the transaction
app_time
The time of issuance of Virtual Account
van_txid
NHN KCP UNIQUE ID for the transaction
va_reciept_gubn
Cash Receipt registration classification
shop_status
Transaction Settlement Status
van_status
VAN Payment status
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
amount
The payment amount for the transaction
tno
transaction number
van_code
Mobile Payment Issuer (Carrier) Code
commid
The Mobile Carrier code
mobile_no
Mobile number for the transaction
app_time
The time of issuance of mobile billing
hp_mny
The payment amount for the transaction
stat_hp_cd
The final status of the transaction
shop_status
Transaction Settlement Status
van_status
VAN Payment status
Voucher Payment Query Response Parameters
amount
The payment amount for the transaction
tno
transaction number
tk_van_code
Voucher company code
tk_app_no
Voucher authorization number
tk_app_time
The time of payment using voucher
shop_status
Transaction Settlement Status
van_status
VAN Payment status
Kakao Money Query Response Parameters
kakaomny_mny
The payment amount for the transaction
tno
transaction number
app_kakaomny_time
The time of issuance of eWallets
service_corp_id
KakaoMoney company code
shop_status
Transaction Settlement Status
van_status
VAN Payment status
NaverPay Point Query Response Parameters
naverpoint_mny
The payment amount for the transaction
tno
transaction number
app_easypoint_time
The time of issuance of eWallets
service_corp_id
NaverPay company code
app_cash_receipt_no
The Cash Receipt Transaction Number
shop_status
Transaction Settlement Status
van_status
VAN Payment status