Virtual Account Deposit Webhook

Unlike other payment methods, virtual accounts send webhooks at multiple stages. You must understand and handle each webhook type correctly.

Multi-Stage Webhook Processing Required

For virtual accounts, webhooks are sent at each stage: account issuance, deposit completion, cancellation, refund, etc. You must implement processing logic appropriate for each webhook type.

Webhook Type Summary

Below are all webhook types that occur with virtual accounts. Use a combination of outStatCd and bizType to distinguish webhook types.

Webhook Type	outStatCd	bizType	When It Occurs	Merchant Action
Issuance Complete	`0051`	`A0`	When virtual account is issued (excluding Fixed-type Recurring)	Inform customer of account number, change status to awaiting deposit
Deposit Complete	`0021`	`B1`	When customer completes deposit	Process payment completion, provide product/service
Issuance Cancel	`0021`	`A2`	When merchant calls the issuance cancel API	Process order cancellation
Auto-Cancel	`0121`	`B2`	When transaction is auto-cancelled due to bank issue after deposit	Process transaction cancellation (activated upon request to sales representative)
Refund Complete	`0021`	`C0`	When refund registration is complete after refund API call	Change to refund completed status (actual customer deposit on next business day, no separate webhook thereafter)

NOTE

010 Virtual Account Webhook — See Separate Documentation

For 010 virtual account (bizType=A4) issuance/deposit webhooks, refer to the dedicated 010 virtual account webhook documentation.

Fixed-type Recurring — No Issuance Webhook

For acntType=3 (Fixed-type Recurring) accounts, the issuance complete webhook (0051) is not sent, and the deposit complete webhook (0021/B1) is received by default. If the auto-cancel webhook is enabled, the auto-cancel webhook (0121/B2) is also received. The transmitted parameters differ from Rotating-type/Fixed-type, so handle each section separately as described below.

Webhook Type Details

1. Issuance Complete Webhook

outStatCd: 0051 bizType: A0

Sent when the customer selects a virtual account in the checkout and issuance is completed.

Merchant Actions:

Inform the customer of the issued virtual account number (vAcntNo) and deposit deadline (expireDt)
Change order status to "Awaiting Deposit"
Payment is not yet complete, so do not provide products/services yet

Key Parameters:

vAcntNo: Issued virtual account number
bankNm, bankCd: Bank information
expireDt: Deposit expiration date and time
trdAmt: Amount to be deposited

2. Deposit Complete Webhook

outStatCd: 0021 bizType: B1

Sent when the customer completes a deposit to the issued virtual account.

Merchant Actions:

Process actual payment completion (deduct inventory, confirm order, etc.)
Begin providing products/services
Notify customer of payment completion

Key Parameters:

dpstrNm: Actual depositor name (may differ from the name entered at issuance)
trdAmt: Deposited amount
csrcIssNo: Cash receipt approval number (if issued; Rotating-type/Fixed-type only)

NOTE

Depositor Name Mismatch

dpstrNm (actual depositor name) may differ from the name entered at the time of order. Since deposits may be made from another person's account, use this field for reference only.

3. Issuance Cancel Webhook

outStatCd: 0021 bizType: A2

Sent when the merchant calls the issuance cancel API.

Merchant Actions:

Change order status to "Cancelled"
Notify customer of payment cancellation

No Webhook Upon Deposit Deadline Expiration

No separate webhook is sent when the deposit deadline (expireDt) expires. The merchant must implement expiration handling logic based on expireDt.

4. Auto-Cancel Webhook

outStatCd: 0121 bizType: B2

Sent when a transaction is automatically cancelled after a customer deposit due to a bank issue (account error, limit exceeded, etc.). This webhook is sent only to merchants for which the auto-cancel webhook setting has been enabled.

Available Only After Request to Sales Representative

Auto-cancel webhooks are not provided by default and must be enabled by requesting activation from your sales representative.

Merchant Actions:

Change order status to "Cancelled"
Notify customer of payment cancellation and request re-payment

5. Refund Complete Webhook

outStatCd: 0021 bizType: C0

Sent when the merchant calls the refund API and Hecto Financial completes the refund registration.

Actual Customer Account Deposit on Next Business Day — No Separate Webhook Thereafter

Upon receiving this webhook, the merchant should process the refund as complete. The actual deposit to the customer's account will be processed on the next business day, and no separate webhook will be sent upon deposit completion.

Merchant Actions:

Change order status to "Refund Complete"
Notify customer of refund completion (inform them that the account deposit is scheduled for the next business day)

Key Parameters:

orgTrdNo: Original transaction number
orgTrdDt: Original transaction date
cnclType: Cancellation type (00: Full, 10: Partial)

NOTE

What is notiUrl?

notiUrl is a Server-to-Server webhook that directly sends the payment result from the PG server to the merchant server. It does not go through the browser, allowing stable receipt of results.

For detailed information, refer to the Result Notification URL Guide.

Communication Specification

Item	Description
Method	`POST`
Content-Type	`application/x-www-form-urlencoded; charset=UTF-8`
Response Format	Plain Text (`OK` or `FAIL`)

Webhook Parameters — Rotating-type / Fixed-type

Webhook parameters sent from Rotating-type (acntType=1) and Fixed-type (acntType=2) virtual accounts. Used for all webhook types including Issuance Complete (0051), Deposit Complete (0021), and Auto-Cancel (0121, when enabled).

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

└outStatCdN(4)Numeric, up to 4 bytes*Transaction status0021

Transaction status

0021: Success (deposit complete/issuance cancel/refund — distinguished by bizType) 0051: Virtual account awaiting deposit (issuance complete) 0121: Auto-cancel (when enabled)

└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number assigned by Hecto FinancialSTFP_PGVAnxva_jt_il0211129135810M1494620

Unique transaction number assigned by Hecto Financial

└methodA(2)Alphabetic, up to 2 bytes*Payment methodVA

Payment method

VA: Virtual Account

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business typeA0

Business type

A0: Issuance A2: Issuance Cancel B1: Deposit Webhook B2: Auto-Cancel (when enabled) C0: Refund

└mchtIdAN(12)Alphanumeric, up to 12 bytes*Merchant ID assigned by Hecto Financialnxva_jt_il

Merchant ID assigned by Hecto Financial

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchantORDER20211231100000

Unique order number generated by the merchant

└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesThe name of the customer who completed this paymentMerchantName_HongGilDong

The name of the customer who completed this payment

└mchtNameAHN(20)Alphanumeric + Korean, up to 20 bytesActual seller name. If no actual seller name is provided in the transaction request, the merchant name contracted with Hecto Financial is used.Hecto Financial

Actual seller name. If no actual seller name is provided in the transaction request, the merchant name contracted with Hecto Financial is used.

└pmtprdNmAHN(128)Alphanumeric + Korean, up to 128 bytesProduct name ordered by the customerTest Product

Product name ordered by the customer

└trdDtmN(14)Numeric, up to 14 bytes*Transaction date and time. Format: YYYYMMDDhhmmss20211231100000

Transaction date and time. Format: YYYYMMDDhhmmss

└trdAmtN(12)Numeric, up to 12 bytesTransaction amount1000

Transaction amount

└bankCdAN(10)Alphanumeric, up to 10 bytesBank code011

Bank code

└bankNmAHN(10)Alphanumeric + Korean, up to 10 bytesBank nameNH NongHyup

Bank name

└acntTypeN(1)Numeric, up to 1 bytesAccount type1

Account type

1: Default (Rotating-type) 2: Fixed-type 3: Fixed-type Recurring

└vAcntNoN(64)Numeric, up to 64 bytesVirtual account number0123456789

Virtual account number

└expireDtN(14)Numeric, up to 14 bytesVirtual account deposit expiration date and time20271231235959

Virtual account deposit expiration date and time

└AcntPrintNmAHN(12)Alphanumeric + Korean, up to 12 bytesBank statement description displayed on the customer's bank statement. The value passed in the payment request is used. If no value, the merchant name contracted with Hecto Financial is used.Hecto Financial

Bank statement description displayed on the customer's bank statement. The value passed in the payment request is used. If no value, the merchant name contracted with Hecto Financial is used.

└dpstrNmAHN(30)Alphanumeric + Korean, up to 30 bytesName of the person who actually deposited into the virtual account (provided in the deposit webhook)Hong Gil-dong

Name of the person who actually deposited into the virtual account (provided in the deposit webhook)

└emailAN(60)Alphanumeric, up to 60 bytesMerchant customer emailHongGilDong@example.com

Merchant customer email

└mchtCustIdAN(50)Alphanumeric, up to 50 bytesMerchant customer IDHongGilDong

Merchant customer ID

└orgTrdNoAN(40)Alphanumeric, up to 40 bytesOriginal transaction number for cancellationsSTFP_PGVAnxva_jt_il0211129135810M1494620

Original transaction number for cancellations

└orgTrdDtN(8)Numeric, up to 8 bytesOriginal transaction date for cancellations20211231

Original transaction date for cancellations

└csrcIssNoAN(9)Alphanumeric, up to 9 bytesCash receipt approval number0123456789

Cash receipt approval number

└cnclTypeN(2)Numeric, up to 2 bytesCancellation transaction type00

Cancellation transaction type

00: Full cancellation 10: Partial cancellation

└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesAdditional merchant information field. The value passed in the request is returned as-is.name=HongGilDong&age=25

Additional merchant information field. The value passed in the request is returned as-is.

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA256 hash valuea2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1

SHA256 hash value

NOTE

Hash Generation Combination

outStatCd + transaction date (first 8 digits of trdDtm) + transaction time (last 6 digits of trdDtm) + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey

Webhook Parameters — Fixed-type Recurring

Webhook parameters sent from Fixed-type Recurring (acntType=3) virtual accounts.

Fixed-type Recurring Specific Notes

Fixed-type Recurring accounts do not send an issuance webhook (outStatCd=0051). They receive the deposit complete webhook (outStatCd=0021 / bizType=B1) by default and also receive the auto-cancel webhook (outStatCd=0121 / bizType=B2) when it is enabled. Also, mchtTrdNo is always fixed as '0000000', making it impossible to identify individual orders, so orders must be distinguished using vAcntNo (virtual account number).

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

└outStatCdN(4)Numeric, up to 4 bytes*Transaction status. Deposit complete is 0021 by default; 0121 is also received when the auto-cancel webhook is enabled.0021

Transaction status. Deposit complete is 0021 by default; 0121 is also received when the auto-cancel webhook is enabled.

0021: Deposit complete 0121: Auto-cancel (when enabled)

└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number assigned by Hecto FinancialSTFP_PGVAnxva_fix20211129135810M1494620

Unique transaction number assigned by Hecto Financial

*For Fixed-type Recurring, this is a per-deposit transaction number and differs from the transaction number issued at issuance. Use this deposit transaction number as the original transaction number (orgTrdNo) for follow-up transactions such as refunds.

└methodA(2)Alphabetic, up to 2 bytes*Payment methodVA

Payment method

VA: Virtual Account

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type. Deposit notification is B1 by default; B2 is also received when the auto-cancel webhook is enabled.B1

Business type. Deposit notification is B1 by default; B2 is also received when the auto-cancel webhook is enabled.

B1: Deposit notification B2: Auto-cancel (when enabled)

└mchtIdAN(12)Alphanumeric, up to 12 bytes*Merchant ID assigned by Hecto Financialnxva_fix2

Merchant ID assigned by Hecto Financial

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Fixed-type Recurring accounts always send '0000000' as a fixed value. Use vAcntNo to distinguish orders.0000000

Fixed-type Recurring accounts always send '0000000' as a fixed value. Use vAcntNo to distinguish orders.

└trdDtmN(14)Numeric, up to 14 bytes*Transaction date and time. Format: YYYYMMDDhhmmss20211231100000

Transaction date and time. Format: YYYYMMDDhhmmss

└trdAmtN(12)Numeric, up to 12 bytesTransaction amount1000

Transaction amount

└bankCdAN(10)Alphanumeric, up to 10 bytesBank code011

Bank code

└bankNmAHN(10)Alphanumeric + Korean, up to 10 bytesBank nameNH NongHyup

Bank name

└acntTypeN(1)Numeric, up to 1 bytesAccount type. Fixed-type Recurring is always 3.3

Account type. Fixed-type Recurring is always 3.

3: Fixed-type Recurring

└vAcntNoN(64)Numeric, up to 64 bytesVirtual account number. Since mchtTrdNo is a fixed value, this field must be used to distinguish orders.0123456789

Virtual account number. Since mchtTrdNo is a fixed value, this field must be used to distinguish orders.

└expireDtN(14)Numeric, up to 14 bytesVirtual account deposit expiration date and time20271231235959

Virtual account deposit expiration date and time

Bank statement description displayed on the customer's bank statement. The value passed in the payment request is used. If no value, the merchant name contracted with Hecto Financial is used.

└dpstrNmAHN(30)Alphanumeric + Korean, up to 30 bytesName of the person who actually deposited into the virtual accountHong Gil-dong

Name of the person who actually deposited into the virtual account

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA256 hash valuea2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1

SHA256 hash value

NOTE

Hash Generation Combination

outStatCd + transaction date (first 8 digits of trdDtm) + transaction time (last 6 digits of trdDtm) + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey

Webhook Response (Merchant → Hecto Financial)

The merchant sends a response to Hecto Financial.

Response	Description
`OK`	Success (uppercase). Processed as webhook received.
`FAIL` or others	Recognized as failure; resent up to the configured number of times per merchant. Sending stops after exceeding the resend deadline.

Response Format Note

The response must be plain text 'OK' only. If spaces or other characters are included, it will be considered a failure and resending may occur.

NOTE

Distinguishing Issuance and Deposit Webhooks

If outStatCd is '0051', it is the issuance complete webhook. If it is '0021', it is the deposit complete webhook. Actual payment processing should be performed in the deposit complete webhook (0021).

Hash Verification

Hash Verification Required

To check for data tampering, you must verify the hash data received via notiUrl. Only provide the service when the hash matches.

Item	Combination Fields
pktHash	Transaction status code + transaction date (first 8 digits of trdDtm) + transaction time (last 6 digits of trdDtm) + merchant ID + merchant order number + transaction amount + hash key

Webhook Examples

Deposit Webhook — Rotating-type / Fixed-type (Hecto Financial → Merchant)

POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

outStatCd=0021
&trdNo=STFP_PGVAnxva_sb_il0211231100000M1234567
&method=VA
&bizType=B1
&mchtId=nxva_sb_il
&mchtTrdNo=ORDER20211231100000
&mchtCustNm=HongGilDong
&mchtName=HectoFinancial
&pmtprdNm=Test Product
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&vAcntNo=12345678901234
&dpstrNm=HongGilDong
&acntType=1
&email=test@example.com
&mchtCustId=customer123
&csrcIssNo=
&mchtParam=
&pktHash=a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1

Deposit Webhook — Fixed-type Recurring (Hecto Financial → Merchant)

POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

outStatCd=0021
&trdNo=STFP_PGVAnxva_fix20211231120000M9876543
&method=VA
&bizType=B1
&mchtId=nxva_fix2
&mchtTrdNo=0000000
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&bankNm=NH NongHyup
&vAcntNo=2022011000001
&dpstrNm=HongGilDong
&acntType=3
&AcntPrintNm=HectoFinancial
&expireDt=20271231235959
&pktHash=b3e7f498c66e8d1a790cbb3f9dc2eef1b48a5c2594c6a0ae2f72cge059654f2

Response (Merchant → Hecto Financial)

OK

Need technical support?

Code Samples

HectoFinancial GitHub