헥토파이낸셜 개발자센터

Virtual Account Payment (Checkout)

The Checkout method allows customers to issue a virtual account number directly on the payment screen and make a deposit.

Test Key Information

API Information

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

Important Notes

Virtual Account Deposit Notice

A virtual account is valid from issuance until the expiration date. The deposit amount must exactly match the configured amount for automatic approval.
  • Virtual account numbers are unique and will not be issued as duplicates.
  • Deposits are not possible after the expiration date.
  • Upon deposit completion, the result can be received via webhook (notiUrl).

Request Parameters

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

Required Parameters

└mchtIdAN(10)Alphanumeric, up to 10 bytes*
Unique merchant ID assigned by Hecto Financial
nx_mid_il: Virtual Account
└methodAN(20)Alphanumeric, up to 20 bytes*
Payment type code for the PG service
*Fixed value
└trdDtN(8)Numeric, up to 8 bytes*
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Request time (HH24MISS)
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant (Korean characters excluded)
└mchtNameAHN(100)Alphanumeric + Korean, up to 100 bytes*
Merchant name (Korean)
└mchtENameAN(100)Alphanumeric, up to 100 bytes*
Merchant name (English)
└pmtPrdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Payment product name
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
Webhook URL to receive the result after deposit completion (Server-to-Server integration URL)
└nextUrlAN(250)Alphanumeric, up to 250 bytes*
URL to redirect to the result screen after virtual account issuance
*Redirected when a button inside the checkout is clicked. Check the outStatCd value to confirm issuance success (0051) or failure (0031).
└cancUrlAN(250)Alphanumeric, up to 250 bytes*
URL to redirect to when the customer clicks the X button on the checkout
*Browser close, back navigation, etc. are not detected.
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
Hash value generated using SHA256
NOTE

Hash Generation Combination

mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt (plaintext) + hashKey

Optional Parameters

└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer name
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field for entering additional order information
└emailAN(60)Alphanumeric, up to 60 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Email address
└prdtTermN(14)Numeric, up to 14 bytes
Product provision period (yyyyMMddHHmmss). If empty, displayed as a regular payment.
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Unique customer ID or unique key sent by the merchant
└custAcntSumryAHN(50)Alphanumeric + Korean, up to 50 bytes
Bank statement description. Name displayed on the customer's bank statement. If empty, the merchant's Korean name is used.
└expireDtN(14)Numeric, up to 14 bytes
Deposit expiration date and time (yyyyMMddHHmmss)
*Minimum: 1 hour from the current time. Maximum: 365 days from the current date. If not set, defaults to 10 days from the transaction date.
└cphoneNoN(11)Numeric, up to 11 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Mobile phone number (hyphens removed)
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status. If empty, follows merchant settings.
N: Taxable Y: Tax-exempt G: Mixed taxation
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed taxation)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed taxation)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed taxation)
└custIpAN(15)Alphanumeric, up to 15 bytes
Customer IP address. This should be the customer device's IP, not the merchant server's IP.

Response Parameters

Upon successful virtual account issuance, the customer is redirected to nextUrl with the response parameters listed below. If the customer exits the checkout without completing the flow, they are redirected to cancUrl without these parameters. The deposit confirmation is delivered separately via webhook (notiUrl) once the customer makes a deposit.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*nx_mid_il
Unique merchant ID assigned by Hecto Financial
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0051
Transaction status code (success/failure)
0051: Issuance success (awaiting deposit) 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Decline code. If the transaction status is '0031', a detailed code is provided.
*Refer to the decline code table
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message (URL Encoding, UTF-8)
└methodAN(20)Alphanumeric, up to 20 bytes*vbank
Payment type code for the PG service
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Unique order number generated by the merchant
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGVBnxvb_jt_il0211129135810M1494620
Hecto Financial transaction number
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└vtlAcntNoN(30)Numeric, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding1234567890123456
Issued virtual account number
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└fnNmAH(50)Alpha + Korean, up to 50 bytesKB Kookmin Bank
Virtual account bank name
└fnCdN(4)Numeric, up to 4 bytes004
Virtual account bank code
└expireDtN(14)Numeric, up to 14 bytes20271231235959
Virtual account deposit deadline (yyyyMMddHHmmss)
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5PaddingHongGilDong
Merchant customer ID
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└authDtN(14)Numeric, up to 14 bytes20211231100000
Approval date and time (virtual account order/issuance date and time)
└reqIssueDtN(14)Numeric, up to 14 bytes20211231100000
Issuance request date and time (for 010 virtual accounts)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesname=HongGilDong&age=25
The value sent in the request is returned unchanged in the response (pass-through field)

Webhook (Deposit Notification)

For virtual accounts, two webhooks are sent: an Issuance Webhook and a Deposit Webhook.

Two-Stage Webhook Processing Required

For virtual accounts, a webhook is sent both when the account is issued (Issuance Webhook) and when the actual deposit is completed (Deposit Webhook). Both webhooks must be handled. View Webhook Documentation
💬

Need technical support?