헥토파이낸셜 개발자센터

010 Virtual Account Issuance API

An API for issuing a 010 virtual account number after completing phone ownership verification.

Test Key Information

API Information

POST/spay/APIVBank.do
Content-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APIVBank.do
운영https://gw.settlebank.co.kr/spay/APIVBank.do

Important Notes

Required Checks Before Issuance

Phone ownership verification (S1, S2) must be completed before calling the issuance API. The same mchtTrdNo used in the verification request must be used.
  • The issued virtual account is a Kbank (089) account.
  • B2C: The bank statement name is fixed as "010가상계좌".
  • B2B: The bank statement name follows the format "010_CustomerName".
  • For B2B use, the virtual account number follows the format: phone number + 3 digits.

Request Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*
Unique merchant ID assigned by Hecto Financial
└verAN(4)Alphanumeric, up to 4 bytes*
Message version
└methodA(2)Alphabetic, up to 2 bytes*
Payment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*
Business type code
*A4: 010 Virtual Account Issuance
└encCdN(2)Numeric, up to 2 bytes*
Encryption type code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Merchant order number (must be identical to the one used during phone ownership verification)
└trdDtN(8)Numeric, up to 8 bytes*
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Request time (HHmmss)
└mobileYnA(1)Alphabetic, up to 1 bytes
Mobile indicator
Y: Mobile web/app N: PC or other
└osTypeA(1)Alphabetic, up to 1 bytes
OS type
A: Android I: IOS W: Windows M: Mac E: Other

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA-256(실시간 생성)
Hash value generated using SHA256
*Request date + request time + merchant ID + merchant order number + transaction amount (plaintext) + hash key
└bankCdAN(3)Alphanumeric, up to 3 bytes*
Virtual account bank code
*Fixed to Kbank
└vAcntNoN(14)Numeric, up to 14 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Virtual account number to be issued (phone number). For B2B, append 3 digits to the phone number.
└expireDateN(14)Numeric, up to 14 bytes*
Deposit expiry datetime (yyyyMMddHHmmss)
*B2C: current date + max 27 days, B2B: current date + max 3 years. Defaults to +10 days if blank.
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Product name
└sellerNmAHN(128)Alphanumeric + Korean, up to 128 bytes
Seller name
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytes*
Orderer name
└trdAmtN(9)Numeric, up to 9 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
*B2C: actual transaction price, B2B: 1 KRW or more (unrelated to actual deposit webhook amount)
└dpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytes
Account holder name
*B2C: not used (fixed value), B2B: must send the value from the phone ownership verification response
└taxTypeCdA(1)Alphabetic, up to 1 bytes*
Tax exemption status. Follows merchant settings if blank.
N: Taxable Y: Tax-exempt G: Mixed tax
└taxAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed tax)
└vatAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed tax)
└taxFreeAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed tax)
└escrAgrYnA(1)Alphabetic, up to 1 bytes*
Escrow usage
Y: Agree N: Disagree
└escrPwdAN(64)Alphanumeric, up to 64 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Escrow password (required when using escrow)
└rfdDpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Account holder name for escrow refund (required when using escrow)
└csrcIssReqYnA(1)Alphabetic, up to 1 bytes*
Cash receipt issuance
Y: Issue N: Do not issue
└cashRcptPrposDivCdN(1)Numeric, up to 1 bytes
Cash receipt purpose code (required when using cash receipt)
0: Income deduction 1: Expenditure proof
└csrcRegNoDivCdN(1)Numeric, up to 1 bytes
Cash receipt registration number type code (required when using cash receipt)
1: Card 2: Resident registration number 3: Business registration number 4: Phone number
└csrcRegNoAN(64)Alphanumeric, up to 64 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Cash receipt unique identification information (required when using cash receipt)
└emailAN(60)Alphanumeric, up to 60 bytes
User email (required when using escrow)
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
URL of the page where the result is delivered after payment (Server-to-Server integration URL)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field (bypassed as-is in response)
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes*
Merchant customer ID

Response Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxva_sb_il
Merchant ID
└verAN(4)Alphanumeric, up to 4 bytes*0A18
Message version
└methodA(2)Alphabetic, up to 2 bytes*VA
Payment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*A4
Business type code
└encCdN(2)Numeric, up to 2 bytes*23
Encryption type code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Merchant order number
└trdNoAN(40)Alphanumeric, up to 40 bytes*STBK_0123456789
Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*20211231
Request date
└trdTmN(6)Numeric, up to 6 bytes*120000
Request time
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Result code (0000 indicates success)
*VA03: For B2B use, an already-issued virtual account number exists
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*75ac014c33165f3ee0c331123a0049f37a6e1578f8cec1d3d0374ffb75f18496
Response hash value
└bankCdAN(3)Alphanumeric, up to 3 bytes*089
Virtual account bank code
└vAcntNoN(14)Numeric, up to 14 bytes*AES-256AES-256/ECB/PKCS5Padding01012345678
Issued virtual account number
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)Numeric, up to 14 bytes*20211231235959
Deposit expiry datetime (yyyyMMddHHmmss)
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Test Product
Product name
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytes*Hong Gil-dong
Orderer name
└trdAmtN(9)Numeric, up to 9 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└dpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytes*010가상계좌
Account holder name
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes*HongGilDong
Merchant customer ID

Request Example

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "A4",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "120000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "hash value",
    "bankCd": "089",
    "vAcntNo": "AES-encrypted phone number",
    "expireDate": "20211231235959",
    "prdtNm": "Test Product",
    "sellerNm": "Hecto Financial",
    "ordNm": "Hong Gil-dong",
    "trdAmt": "AES-encrypted amount",
    "dpstrNm": "010가상계좌",
    "taxTypeCd": "N",
    "escrAgrYn": "N",
    "csrcIssReqYn": "N",
    "mchtCustId": "HongGilDong"
  }
}

Response Example

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "A4",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "STBK_0123456789",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "Processed successfully."
  },
  "data": {
    "pktHash": "response hash value",
    "bankCd": "089",
    "vAcntNo": "AES-encrypted virtual account number",
    "expireDate": "20211231235959",
    "prdtNm": "Test Product",
    "ordNm": "Hong Gil-dong",
    "trdAmt": "AES-encrypted amount",
    "dpstrNm": "010가상계좌",
    "mchtCustId": "HongGilDong"
  }
}
💬

Need technical support?