Fixed/Unlimited Virtual Account API
The Fixed-type Recurring (acntType=3) method allows continuous reuse of a single issued virtual account number to accept repeated deposits. Unlike the Rotating-type which issues a new number for each transaction, this method uses a pre-assigned account number dedicated to a specific customer.
Test Key Information
Important Notes
Prior Consultation Required
The Fixed-type Recurring method is only available to merchants who have completed prior consultation with Hecto Financial. The merchant ID and virtual account number list must be issued separately.
NOTE
Cash Receipt Separate Call Required
For the Fixed-type Recurring method, the cash receipt API must be called separately. View Cash Receipt Issuance API
Webhook-Related Notes
At the time of issuance, the issuance complete webhook (outStatCd: 0051) is not sent; issuance success is confirmed only via the API response.
The deposit complete webhook (bizType: B1) is sent normally, but the webhook URL must be requested through your sales representative and registered in the merchant configuration.
- The transaction amount (
trdAmt) must always be set to0. vAcntNo(virtual account number) is selected from the pre-issued list.- The deposit expiration date (
expireDate) can be set to unlimited. However, issuance cancellation is only possible within 1 year of the issuance date. - For virtual account bank codes, refer to the Virtual Account Bank Codes list.
API Information
POST/spay/APIVBank.do
Content-Type
application/json테스트
https://tbgw.settlebank.co.kr/spay/APIVBank.do운영
https://gw.settlebank.co.kr/spay/APIVBank.doRequest 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
Unique merchant ID assigned by Hecto Financial
nxva_fix2: Fixed-type Recurring exclusive└verAN(4)Alphanumeric, up to 4 bytes*Message version
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*Payment method
Payment method
*Fixed value (Virtual Account)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
Business type code
*Fixed value (Issuance)
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant
Unique order number generated by the merchant
└trdDtN(8)Numeric, up to 8 bytes*Date the message is sent (YYYYMMDD)
Date the message is sent (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Time the message is sent (HHMMSS)
Time the message is sent (HHMMSS)
└mobileYnA(1)Alphabetic, up to 1 bytesMobile indicator
Mobile indicator
Y: Mobile web/app N: PC or other└osTypeA(1)Alphabetic, up to 1 bytesOS type
OS type
A: Android I: IOS W: Windows M: Mac E: Otherdata Object
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256Hash value generated using SHA256(실시간 생성)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
Virtual account bank code
*Refer to the Virtual Account Bank Code List. In the sandbox environment, only 004 (KB Kookmin Bank) and 011 (NH NongHyup Bank) are available.
└acntTypeN(1)Numeric, up to 1 bytes*Account type
Account type
3: Fixed-type Recurring (pre-assigned account for repeated use)└vAcntNoN(16)Numeric, up to 16 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Virtual account number (Fixed-type Recurring exclusive)Virtual account number (Fixed-type Recurring exclusive)
*Send the pre-issued fixed virtual account number AES-encrypted. Refer to the sandbox virtual account list.
└expireDateN(14)Numeric, up to 14 bytesDeposit expiration date and time (YYYYMMDDhhmmss)
Deposit expiration date and time (YYYYMMDDhhmmss)
*If not set, automatically configured to 10 days after the transaction date. Can be set to unlimited, but issuance cancellation is only possible within 1 year of the issuance date.
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Product name
Product name
└sellerNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Seller name
Seller name
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytesOrderer name
Orderer name
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amountTransaction amount
*Fixed-type Recurring (acntType=3) must always be set to 0
└dpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytesBank statement description
Bank statement description
*If empty, sellerNm (seller name) is used as the bank statement description.
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesUnique customer ID or unique key sent by the merchant
Unique customer ID or unique key sent by the merchant
Sandbox Fixed-type Recurring Virtual Account List
Fixed-type Recurring virtual account numbers available only in the sandbox environment (tbgw.settlebank.co.kr).
| Merchant ID (mchtId) | Bank Code (bankCd) | Virtual Account Number (vAcntNo) |
|---|---|---|
| nxva_fix2 | 004 (KB Kookmin Bank) | 2022004000056 ~ 2022004000100 |
| nxva_fix2 | 011 (NH NongHyup Bank) | 2022011000056 ~ 2022011000100 |
Response 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_ilUnique merchant ID assigned by Hecto Financial
└verAN(4)Alphanumeric, up to 4 bytes*Message version
0A19Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*Payment method
VAPayment method
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
A0Business type code
*Fixed value (Issuance)
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
23Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique transaction number generated by the merchant
ORDER20211231100000Unique transaction number generated by the merchant
└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number generated by Hecto Financial
STFP_PGVAnx_mid_il00210806075210M1853381Unique transaction number generated by Hecto Financial
└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)
20211231Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)
100000Request time (HHMMSS)
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code (success/failure)
0021Transaction status code (success/failure)
0021: Issuance success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Decline code. If transaction status is '0031', a detailed code is provided.
0000Decline code. If transaction status is '0031', a detailed code is provided.
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message (URL Encoding, UTF-8)
Processed successfully.Result message (URL Encoding, UTF-8)
data Object
└pktHashAN(64)Alphanumeric, up to 64 bytes*Returns the hash value from the request as-is
Returns the hash value from the request as-is
└bankCdAN(3)Alphanumeric, up to 3 bytes*Virtual account bank code
011Virtual account bank code
└vAcntNoN(16)Numeric, up to 16 bytes*
AES-256AES-256/ECB/PKCS5PaddingIssued virtual account number0123456789Issued virtual account number
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)Numeric, up to 14 bytes*Deposit expiration date and time (YYYYMMDDhhmmss)
20271231235959Deposit expiration date and time (YYYYMMDDhhmmss)
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingTransaction amount0Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└acntTypeN(1)Numeric, up to 1 bytes*Account type (returned as-is from the request)
3Account type (returned as-is from the request)
3: Fixed-type Recurring
Need technical support?
Code Samples
HectoFinancial GitHub