API Reference > 가상계좌
가상계좌 발급
가상계좌 발급
고객이 원하는 은행의 가상계좌를 발급받을 수 있습니다.
테스트 : https://stg-spl.kcp.co.kr/gw/hub/v1/payment
운영 : https://spl.kcp.co.kr/gw/hub/v1/payment
Header
Protocol: HTTPS
HTTP Method: POST
Content-Type: application/json; charset=UTF-8
Request Body 파라미터
{
"site_cd":"T0000",
"pay_method":"VCNT",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----MIIDjDCCAnSgAwIBAgIK8gGsiPI-----END CERTIFICATE-----",
"amount":"1004",
"currency":"410",
"ordr_idxx":"TEST1234567890",
"buyr_name":"홍길동",
"buyr_tel2":"01012341234",
"buyr_mail":"이메일주소",
"va_txtype":"41100000",
"va_mny":"1004",
"va_bankcode":"BK26",
"va_name":"홍길동",
"va_date":"20250830235959",
"va_receipt_gubn":"0",
"va_taxno":"0101234123",
}site_cd필수PC / Mobile
길이가 5자리로 영문대문자 또는 영문대문자 + 숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "T0007"
kcp_cert_info필수PC / Mobile
NHN KCP에서 발급하는 서비스 인증서로, 모든 서비스에서 사용됩니다.
상점관리자의 인증센터에서 다운받은 pem 파일 내용을 직렬화하여 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…………Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----"
pay_method필수PC / Mobile
결제수단으로 가상계좌 발급 시에는 'VCNT' 고정 값이 사용됩니다. ex) 가상계좌 경우, "pay_method" : "VCNT"
amount필수PC / Mobile
결제 금액
결제 건의 총 결제 금액이 리턴 됩니다.
최종 결제 금액의 처리는 승인완료 후 리턴 데이터 중 amount 로 처리하여야 하며 반드시 업체의 DB금액과 비교하여 검증하시기 바랍니다.
ex) "amount" : "1000"
currency필수PC / Mobile
화폐단위, 가상계좌 서비스는 원화결제만 지원합니다.
ex) 원화 - 410, "currency" : "410"
va_txtype필수PC / Mobile
가상계좌 발급 타입으로 ‘41100000’ 의 고정 값이 사용됩니다
ex) "va_txtype" : "41100000"
va_mny필수PC / Mobile
가상계좌 발급 금액입니다. amount와 동일한 금액을 입력하시기 바랍니다.
ex) "va_mny" : "1000"
va_bankcode필수PC / Mobile
발급할 가상계좌의 은행 코드입니다.
ex)"va_bankcode"="BK26"
va_name필수PC / Mobile
가상계좌 입금자 이름 입니다.
ex) "va_name" : "홍길동"
va_date필수PC / Mobile
가상계좌 입금 마감 시각입니다. YYYYMMDDHHMMSS 형식으로 사용합니다.
ex) "va_date" : "20260530235959"
ordr_idxx필수PC / Mobile
상점에서 관리하는 주문번호입니다. 최대길이는 40자이며, 중복되지 않는 유니크한 값으로 사용하시길 권장합니다.
주문 데이터 관리를 위해 가맹점에서 반드시 저장해야합니다.
ex) "ordr_idxx" : "TEST123456789"
good_name필수PC / Mobile
상품명입니다.
ex) "good_name" : "운동화"
buyr_name필수PC / Mobile
주문자이름
ex) "buyr_name" : "홍길동"
good_cdPC / Mobile
상품코드
주문상품명으로 구분이 어려운 경우 상품군을 따로 구분하여 처리할 수 있는 기능
ex) "good_cd" : "00"
buyr_tel2PC / Mobile
주문자 휴대폰번호
하이폰(-)포함 가능
ex) "buyr_tel2" : "010-1234-1234"
buyr_mailPC / Mobile
주문자 이메일
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.
tax_flagPC / Mobile
복합 과세 구문
NHN KCP 복합과세로 설정한 가맹점에서만 사용 가능하며 TG03 : 복합과세 고정 값을 사용
ex) "tax_flag" : "TG03"
comm_tax_mnyPC / Mobile
공급가액
공급가액 = good_mny / 1.1
ex) "comm_tax_mny" : "909"
comm_free_mnyPC / Mobile
비과세액
ex) "comm_free_mny" : "0"
comm_vat_mnyPC / Mobile
부가가치세
부가가치세 = good_mny – 과세 공급가액 - 비과세액
ex) "comm_vat_mny" : "91"
va_receipt_gubnPC / Mobile
현금영수증 발행 용도입니다.
현금영수증 발급이 필요한 경우 사용하며, 소득공제와 지출증빙 중 설정합니다.
소득공제(개인) : 0, 지출증빙(사업자) : 1
ex) "va_receipt_gubn" : "0"
va_taxnoPC / Mobile
현금영수증 발급 요청 식별 번호입니다.
소득공제 : 휴대폰 번호, 현금영수증 카드번호
지출증빙 : 사업자번호, 현금영수증 카드번호
* 문자 사용 불가합니다.
ex) "va_taxno" : "01012341234""
Response 파라미터
가상계좌는 다른 결제수단과 다르게 가상계좌 발급 API를 호출하면 가상계좌가 발급된 것이지, 결제가 완료된 게 아닙니다.
따라서 가상계좌 발급은 [V000] 로 응답되는 점을 유의해 주세요.
{
"res_cd":"0000",
"res_msg":"정상처리-테스트거래입니다.",
"res_en_msg":"The virtual account is issued.",
"pay_method":"VCNT",
"tno":"20250521435727",
"order_no":"TEST1234567890",
"amount":"1004",
"account":"T2609260001713",
"bankname":"신한은행",
"bankcode":"BK26",
"depositor":"NHN KCP",
"app_time":"20250729180240",
"va_date":"20250830235959",
}res_cdPC / Mobile
결과코드
정상 처리 된 경우 ‘0000’ 값 리턴
ex) "res_cd" : "0000"
res_msgPC / Mobile
결과메세지
ex) "res_msg" : "정상처리"
res_en_msgPC / Mobile
영문 결과 메세지입니다. 정상 처리 된 경우 'The virtual account is issued'를 리턴합니다.
ex) "res_en_msg" : "processing completed"
tnoPC / Mobile
NHN KCP 거래건의 거래번호입니다.
ex) "tno" : "24822014611200”
order_noPC / Mobile
Order number
가맹점에서 생성한 주문번호
ex) "order_no": "TEST123456789"
amountPC / Mobile
가상계좌 발급 금액
고객 입금 시, 발급 금액과 다른 금액으로 입금 시도 할 경우 금액 불일치로 입금 거절이 됩니다.
발급된 금액으로만 입금이 가능하며, 금액 설정을 잘못한 경우 가상계좌 재발급을 받아야 합니다.
ex) "amount" : "1000"
accountPC / Mobile
발급된 가상계좌 번호입니다. 테스트 환경에서는 T로 시작하는 가상계좌 번호가 발급됩니다.
ex) "account" : "T2695797201822"
banknamePC / Mobile
발급된 가상계좌의 은행명
ex) "bankname" : "신한은행"
bankcodePC / Mobile
은행코드
ex) "bankcode" : "BK26"
depositorPC / Mobile
예금주명
가맹점명이 예금주명으로 설정되어 리턴됩니다.
ex) "account" : "56201234123412"
app_timePC / Mobile
가상계좌 발급 시각입니다. YYYYMMDDHHMMSS 형식으로 리턴됩니다.
ex) "app_time" : "20260101235959"
va_datePC / Mobile
가상계좌 입금 마감 시각입니다. YYYYMMDDHHMMSS 형식으로 사용합니다.
ex) "va_date" : "20260530235959"
가상계좌 입금
가상계좌 입금
테스트 환경에서는 가상계좌 번호 발급 후 입금대기 상태의 결제 건을 입금완료로 변경할 수 있는 모의 입금 페이지를 제공합니다.
모의입금을 통해 입금완료 상태로 변경되면서, Webhook 테스트를 진행할 수 있습니다.
모의 입금 테스트 페이지
https://testadmin.kcp.co.kr/Modules/Noti/TEST_Vcnt_Noti.jsp
입금 데이터 전송 (NHN KCP → 가맹점)
NHN KCP에서 가맹점으로 드리는 입금통보 데이터입니다.
{
"site_cd":"T0000",
"tno":"20250521435727",
"order_no":"TEST1234567890",
"tx_cd":"TX00",
"tx_tm":"20250521120000",
"ipgm_mnyx":"1004",
"ipgm_name":"홍길동",
"ipgm_time":"20250521120000",
"totl_mnyx":"1004",
"bank_code":"20",
"account":"T2609260001713",
"noti_id":"25052120165018047733",
"op_cd":"50",
"remitter":"홍길동",
"cash_a_no":"591605898",
"cash_no":"25794127150936",
}site_cd
NHN KCP 발급 사이트(상점)코드
ex) "site_cd": "T0000"
tnoPC / Mobile
NHN KCP 거래 고유번호
※ 거래고유번호 전체로 사용 하시기 바랍니다. (임의의 숫자나 파싱하여 사용 불가)
전송된 가상계좌 결제 건의 tno가 전달 됩니다.
ex) “tno” : “24123456789012”
order_no
가맹점에서 생성한 주문번호
ex) "order_no": "TEST123456789"
tx_cd
업무처리 구분코드
가상계좌 입금 통보 – TX00
ex) "tx_cd": "TX00"
tx_tm
통보된 업무에 대한 업무처리 완료 시간
ex) "tx_tm": "20260101235959"
ipgm_namePC / Mobile
거래에 대한 주문자명
ex) “ipgm_name” : “홍길동”
ipgm_mnyxPC / Mobile
입금자가 실제 입금한 입금 금액
ex) “ipgm_mnyx” : “1000”
totl_mnyxPC / Mobile
해당 계좌에 입금 된 금액의 합계
ex) “totl_mnyx” : “1000”
ipgm_timePC / Mobile
가상계좌에 입금된 시간
ex) “ipgm_time” : “20260131235959”
bank_codePC / Mobile
가상계좌 은행코드
ex) “bank_code” : “03”
accountPC / Mobile
입금된 가상계좌 번호
ex) “account” : “56201234123412”
noti_idPC / Mobile
가상계좌의 각 입금 통보 건에 대한 고유한 값을 가지는 변수
ex) “noti_id” : “24013112345678901234”
op_cdPC / Mobile
입급 통보 건에 대한 고유한 값
입금건에 대한 은행 망취소 응답 13 통보.
입금과 망취소 응답이 동일한 noti_id로 발송되니 입금취소 상태 확인이 필요합니다.
op_cd = ‘13’ 은 입금이 잘못 된 경우로 가맹점에 취소 노티가 나갑니다.
ex) “op_cd” : “50”
remitterPC / Mobile
결제 금액을 입금한 입금자명
주문자명과 다를 수 있습니다.
ex) “remitter” : “홍길동”
cash_a_noPC / Mobile
현금영수증 승인번호
ex) “cash_a_no” : “591234567”
cash_noPC / Mobile
가상계좌 발급 시 현금영수증 등록 요청 건에 대해 입금완료 후 리턴 되는 현금영수증 거래번호
ex) “cash_no” : “24123456789012”
입금 취소(op_cd=13) 유의사항
가상계좌 입금 건은 은행 공동망을 통해 입금 취소가 발생할 수 있으며, 이 경우 [op_cd = 13]
으로 전달됩니다.
op_cd=13은 정상 입금 완료가 아니므로, DB 처리 시 반드시 예외 처리해 주세요.
웹훅 응답 데이터 (가맹점 → NHN KCP)
Webhook 으로 통보 받은 데이터를 가맹점 서버에서 정상적으로 저장하였을 경우, NHN KCP로 정상 처리에 대한 결과를 리턴해 주세요.
<input type="hidden" name="result" value="0000">
가상계좌 사용중지
가상계좌 사용중지
발급된 가상계좌에 입금할 수 없도록 사용 중지 API URL로,
서비스 인증서와 서명데이터, tno, mod_type을 전달하여 처리합니다.
테스트 : https://stg-spl.kcp.co.kr/gw/mod/v1/cancel
운영 : https://spl.kcp.co.kr/gw/mod/v1/cancel
Request Body 파라미터
{
"site_cd":"T0000",
"tno":"20250521435727",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"XILKM7AibjMT…. t1fg2LAajA==",
"mod_type":"STSC",
"mod_desc":"단순변심",
"mod_ip":"0.0.0.1",
}site_cd필수PC / Mobile
길이가 5자리로 영문대문자 또는 영문대문자 + 숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "T0007"
kcp_cert_info필수PC / Mobile
NHN KCP에서 발급하는 서비스 인증서로, 모든 서비스에서 사용됩니다.
상점관리자의 인증센터에서 다운받은 pem 파일 내용을 직렬화하여 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…………==-----END CERTIFICATE-----"
kcp_sign_data필수PC / Mobile
서명데이터입니다.
NHN KCP로부터 발급받은 개인키 (PRIVATE KEY)로 SHA256withRSA 알고리즘을 사용하여 문자열을 인코딩하는 방식으로 이루어집니다.
site_cd+"^"+tno+"*"+mode_type 조합으로 생성합니다.
ex) "kcp_sign_data" : "ceCJUAwjijT7+VKVt+...P6wPmg=="
tnoPC / Mobile
NHN KCP 거래건의 거래번호입니다.
ex) "tno" : "24822014611200”
mod_type필수PC / Mobile
취소 타입으로 가상계좌 사용 중지에 대한 값은 'STSC' 고정 값이 사용됩니다.
ex) "mod_type" : "STSC"
mod_descPC / Mobile
가상계좌 사용 중지에 대한 사유를 작성합니다.
ex) "mod_desc" : "고객 변심"
mod_ipPC / Mobile
사용중지 요청 IP입니다.
ex) "mod_ip" : "0.0.0.1"
Response 파라미터
{
"res_cd":"0000",
"res_msg":"정상처리-테스트거래입니다.",
"res_en_msg":"processing completed",
"tno":"20250521435727",
}res_cdPC / Mobile
결과코드
정상 처리 된 경우 ‘0000’ 값 리턴
ex) "res_cd" : "0000"
res_msgPC / Mobile
결과메세지
ex) "res_msg" : "정상처리"
res_en_msgPC / Mobile
영문 결과 메세지입니다. 정상 처리 된 경우 'processing completed'를 리턴합니다.
ex) "res_en_msg" : "processing completed"
tno필수PC / Mobile
NHN KCP 거래건의 거래번호입니다.
ex) "tno" : "24822014611200”