헥토파이낸셜 개발자센터

Issue Virtual Account API

An API that issues virtual accounts directly from the server without a checkout. Supports both Rotating-type and Fixed-type methods.

Test Key Information

Important Notes

Virtual Account Deposit Notice

The deposit amount must exactly match the configured amount for automatic approval. Deposits are not possible after the expiration date.
  • A virtual account is valid from issuance until the expiration date.
  • Deposits are not possible after the expiration date.
  • Virtual account numbers are unique and will not be issued as duplicates.
  • Upon deposit completion, a webhook can be received.
  • Rotating-type (acntType=1): A new virtual account number is issued with each issuance.
  • Fixed-type (acntType=2): A fixed virtual account number is set with an amount and receives deposits.
  • For virtual account bank codes, refer to the Virtual Account Bank Codes list.

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

Request Parameters

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

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*
Unique merchant ID assigned by Hecto Financial
nx_mid_il: Rotating-type nxva_fix: Fixed-type
└verAN(4)Alphanumeric, up to 4 bytes*
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*
Payment method
*Fixed value (Virtual Account)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*
Business type code
*Fixed value (Issuance)
└encCdN(2)Numeric, up to 2 bytes*
Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant
└trdDtN(8)Numeric, up to 8 bytes*
Date the message is sent (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*
Time the message is sent (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
NOTE

Hash Generation Combination

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey
└bankCdAN(3)Alphanumeric, up to 3 bytes*
Virtual account bank code
*Refer to the Virtual Account Bank Code List
└acntTypeN(1)Numeric, up to 1 bytes*
Account type
1: Rotating-type 2: Fixed-type 3: Fixed-type Recurring
*For Fixed-type Recurring (3), set trdAmt to 0 and call the cash receipt API separately.
└vAcntNoN(16)Numeric, up to 16 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Virtual account number (used only for Fixed-type)
*Used only when acntType=2 (Fixed-type).
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
*Expected deposit amount. Automatic approval upon deposit of this amount.
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Product name
└sellerNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Seller name
└expireDateN(14)Numeric, up to 14 bytes
Virtual account deposit deadline (YYYYMMDDhhmmss)
*If not set, default expiration (D+10) applies.
└taxTypeCdA(1)Alphabetic, up to 1 bytes*
Tax type
N: Taxable Y: Tax-exempt G: Mixed taxation
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount of the transaction amount (required for mixed taxation)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount of the transaction amount (required for mixed taxation)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount of the transaction amount (required for mixed taxation)
└escrAgrYnA(1)Alphabetic, up to 1 bytes*
Escrow usage
Y: Use escrow N: Do not use escrow
└escrPwdAN(64)Alphanumeric, up to 64 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Escrow password (required when using escrow)
*Required when escrAgrYn=Y
└rfdDpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Escrow refund account holder name (required when using escrow)
*Required when escrAgrYn=Y
└csrcIssReqYnA(1)Alphabetic, up to 1 bytes*
Cash receipt issuance
Y: Issue cash receipt N: Do not issue cash receipt
└cashRcptPrposDivCdN(1)Numeric, up to 1 bytes
Cash receipt purpose classification code (required when issuing cash receipt)
0: Income deduction 1: Expense proof
*Required when csrcIssReqYn=Y
└csrcRegNoDivCdN(1)Numeric, up to 1 bytes
Cash receipt registration number type code (required when issuing cash receipt)
1: Card 2: Resident registration number 3: Business registration number 4: Mobile phone number
*Required when csrcIssReqYn=Y
└csrcRegNoN(18)Numeric, up to 18 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Cash receipt unique identification information (required when issuing cash receipt)
*Required when csrcIssReqYn=Y. Enter the applicable value: resident registration number / business registration number / mobile phone number / card number.
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytes
Orderer name
└dpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytes
Bank statement description
*Name to be displayed on the customer's bank statement. If empty, sellerNm (seller name) is used as the bank statement description.
└emailAN(60)Alphanumeric, up to 60 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer email address (required when using escrow)
*Required when escrAgrYn=Y
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes
Merchant customer ID
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
Webhook URL to receive the deposit completion result from Hecto Financial to your server
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field for entering additional order information

Sandbox Fixed-type Virtual Account List

Fixed-type virtual account numbers available only in the sandbox environment (tbgw.settlebank.co.kr).

Merchant ID (mchtId)Bank Code (bankCd)Virtual Account Number (vAcntNo)
nxva_fix004 (KB Kookmin Bank)2022004000001 ~ 2022004000050
nxva_fix011 (NH NongHyup Bank)2022011000001 ~ 2022011000050

Response Parameters

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

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*nx_mid_il
Unique merchant ID assigned by Hecto Financial
└verAN(4)Alphanumeric, up to 4 bytes*0A19
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*VA
Payment method
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*A0
Business type code
*Fixed value (Issuance)
└encCdN(2)Numeric, up to 2 bytes*23
Encryption type code
*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_PGVAnx_mid_il00210806075210M1853381
Unique transaction number issued by Hecto Financial
└trdDtN(8)Numeric, up to 8 bytes*20211231
Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*100000
Request time (HHMMSS)
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code (success/failure)
0021: Issuance success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Decline code. If transaction status is '0031', a detailed code is provided.
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message (URL Encoding, UTF-8)

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*
Hash value generated using SHA256
NOTE

Hash Generation Combination

outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└bankCdAN(3)Alphanumeric, up to 3 bytes*004
Virtual account bank code
└vAcntNoN(16)Numeric, up to 16 bytes*AES-256AES-256/ECB/PKCS5Padding12345678901234
Issued virtual account number
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)Numeric, up to 14 bytes*20271231235959
Virtual account deposit deadline (YYYYMMDDhhmmss)
└acntTypeN(1)Numeric, up to 1 bytes*1
Account type (returned as-is from the request)
1: Rotating-type 2: Fixed-type 3: Fixed-type Recurring

Webhook (Deposit Notification)

When a customer deposits into the virtual account, Hecto Financial sends a webhook to your server.

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?