헥토파이낸셜 개발자센터

010 Virtual Account Checkout

This method calls the 010 virtual account checkout (UI) provided by Hecto Financial to issue a virtual account. Phone ownership verification, verification confirm, and issuance are all handled automatically within the checkout.

Test Key Information

API Information

POST/vbank010/main.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbnpg.settlebank.co.kr/vbank010/main.do
운영https://npg.settlebank.co.kr/vbank010/main.do

Important Notes

URL Handling Required

nextUrl is for displaying the payment result screen, and notiUrl is for processing DB updates on the merchant server. If the checkout is force-closed, nextUrl will not be called, so all DB processing must be done in notiUrl.
  • Costs incurred when testing in the production environment are borne by the merchant.
  • HTTPS is recommended for nextUrl, notiUrl, and cancUrl.
  • Avoid using special characters such as :, &, ?, ', ", <, > in request parameters.
  • If reserved words such as href, alert, javascript, or console.log are included in request parameters, they will be automatically removed.

Checkout Types

Typemethod ValueURLDescription
Standalone Checkoutvbank010/vbank010/main.doDedicated checkout for 010 virtual account
Integrated Checkoutvbank/vbank/main.doCheckout integrated with regular virtual account

Request Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*
Unique merchant ID assigned by Hecto Financial
└methodAN(12)Alphanumeric, up to 12 bytes*
Payment method code
vbank: Integrated checkout vbank010: Standalone checkout
└trdDtN(8)Numeric, up to 8 bytes*
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Request time (HHmmss)
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant (no Korean characters)
└mchtNameAHN(100)Alphanumeric + Korean, up to 100 bytes*
Merchant name (Korean)
└mchtENameAN(100)Alphanumeric, up to 100 bytes*
Merchant name (English)
└pmtPrdtNmAHN(50)Alphanumeric + Korean, up to 50 bytes*
Product name for payment
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer name
└custAcntSumryAHN(50)Alphanumeric + Korean, up to 50 bytes
Bank statement description (name printed on the customer's bank statement)
*If blank, the merchant's Korean name is used as the bank statement name
└expireDtN(14)Numeric, up to 14 bytes*
Deposit expiry datetime (yyyyMMddHHmmss)
*If blank, defaults to +10 days from transaction date. B2C: max 27 days, B2B: max 3 years
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
Result processing URL (Server-to-Server integration URL)
*Payment result is sent to the merchant server upon completion. DB processing goes here!
└nextUrlAN(250)Alphanumeric, up to 250 bytes*
Result screen URL (page to navigate to after payment)
*Called when the close button in the checkout is clicked. Not called on force-close.
└cancUrlAN(250)Alphanumeric, up to 250 bytes*
Payment cancel URL (page to navigate to on cancel/failure)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field (bypassed in response)
└emailAN(60)Alphanumeric, up to 60 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer email address
└prdtTermN(14)Numeric, up to 14 bytes
Product provision period (yyyyMMddHHmmss). If empty, displayed as general payment.
└cphoneNoN(11)Numeric, up to 11 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Phone number (without hyphens). Required when skipping phone ownership verification.
*Required if you wish to skip phone ownership verification
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Merchant customer ID. Required when skipping phone ownership verification.
*Required if you wish to skip phone ownership verification
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status
N: Taxable Y: Tax-exempt G: Mixed tax
*If blank, follows merchant settings
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed tax)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed tax)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed tax)
└custIpAN(15)Alphanumeric, up to 15 bytes
Customer IP address (customer device IP, not the merchant server IP)
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
Hash value generated using SHA256
*Merchant ID + payment method + merchant order number + request date + request time + transaction amount (plaintext) + hash key

Response Parameters

When virtual account issuance is complete, the customer is redirected to nextUrl; if the customer clicks the X button in the checkout, they are redirected to cancUrl, and the following parameters are passed. The actual deposit result is delivered to notiUrl (webhook) after the customer deposits.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxva_sb_il
Merchant ID
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0051
Transaction status code
0051: Issuance success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Decline code (detailed code when 0031)
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message (URL Encoding UTF-8)
└methodAN(12)Alphanumeric, up to 12 bytes*vbank010
Payment method
vbank: Integrated checkout vbank010: Standalone checkout
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Merchant order number
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5PaddingHongGilDong
Merchant customer ID
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)Alphanumeric, up to 40 bytes*STBK_0123456789
Hecto Financial transaction number
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytescustom_data
Merchant reserved field (request value bypassed)
└authDtN(14)Numeric, up to 14 bytes20211231120000
Approval datetime (yyyyMMddHHmmss)
└reqIssueDtN(14)Numeric, up to 14 bytes20211231120000
Issuance request datetime (yyyyMMddHHmmss)
└vtlAcntNoN(30)Numeric, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding01012345678
Virtual account number
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDtN(14)Numeric, up to 14 bytes20211231235959
Deposit expiry datetime (yyyyMMddHHmmss)
└fnNmAH(50)Alpha + Korean, up to 50 bytesKbank
Bank name
└fnCdN(4)Numeric, up to 4 bytes089
Bank code

Request Example (HTML Form)

<form id="payForm" method="POST" action="https://tbnpg.settlebank.co.kr/vbank010/main.do">
  <input type="hidden" name="mchtId" value="nxva_sb_il">
  <input type="hidden" name="method" value="vbank010">
  <input type="hidden" name="trdDt" value="20211231">
  <input type="hidden" name="trdTm" value="120000">
  <input type="hidden" name="mchtTrdNo" value="ORDER20211231100000">
  <input type="hidden" name="mchtName" value="Hecto Financial">
  <input type="hidden" name="mchtEName" value="Hecto Financial">
  <input type="hidden" name="pmtPrdtNm" value="Test Product">
  <input type="hidden" name="trdAmt" value="AES-encrypted amount">
  <input type="hidden" name="expireDt" value="20211231235959">
  <input type="hidden" name="notiUrl" value="https://example.com/noti">
  <input type="hidden" name="nextUrl" value="https://example.com/result">
  <input type="hidden" name="cancUrl" value="https://example.com/cancel">
  <input type="hidden" name="pktHash" value="hash value">
  <button type="submit">Pay Now</button>
</form>

Payment Flow

[Buyer, Merchant, Checkout, Hecto Financial]

Buyer -> Merchant : Payment request
Merchant -> Checkout : Checkout call (Form POST)
Checkout -> Buyer : Request phone number input
Buyer -> Checkout : Enter phone number
Checkout -> Hecto Financial : Phone ownership verification request (S1)
Hecto Financial -> Buyer : Send SMS verification code
Buyer -> Checkout : Enter verification code
Checkout -> Hecto Financial : Verification confirm (S2)
Checkout -> Hecto Financial : Issuance request (A4)
Hecto Financial -> Checkout : 010 virtual account issued
Checkout -> Merchant : nextUrl call (response delivered)
Hecto Financial -> Merchant : notiUrl call (issuance webhook)
💬

Need technical support?