Getting Started with VAVS
VAVS (Virtual Account VAN System) relays virtual-account deposits, remittances, and inquiries between a client institution and multiple banks through a single connection.
NOTE
Different from the PG Virtual Account API
This guide covers the TCP/IP fixed-length VAVS protocol, not the HTTP/JSON-based PG Virtual Account API. Messages from the two integration methods are not interchangeable.
Supported Operations
| Operation | Description | Primary Messages |
|---|---|---|
| Deposit | A customer deposits into a virtual account through a branch, CD/ATM, online banking, or telephone banking. | Recipient inquiry 2000, deposit 1000/3000, cancellation 1010/3010 |
| Remittance | The client institution transfers funds for refunds, partner settlement, or other payouts. | Remittance 6010, deposit balance inquiry 6001 |
| Inquiry | Checks deposit eligibility, a virtual-account display name, or the holder name of a remittance destination account. | Recipient inquiry 2000, holder-name inquiry 2001 |
| Reconciliation | Reconciles previous-day deposit and withdrawal counts and amounts. | Summary 7000 |
| Additional Services | Delivers actual depositor names for insurers, missing records, and bank-specific withdrawal-account registration. | 1030, 1033, 5080 |
Deposit Flow
Recipient Inquiry Followed by Deposit
Bank
Hecto Financial
Client Institution
11. Recipient inquiry request (2000)
1. Recipient inquiry request (2000)
22. Recipient inquiry request (2000)
2. Recipient inquiry request (2000)
33. Recipient inquiry response (2100)
3. Recipient inquiry response (2100)
44. Recipient inquiry response (2100)
4. Recipient inquiry response (2100)
55. Deposit request (1000/3000)
5. Deposit request (1000/3000)
66. Deposit request (1000/3000)
6. Deposit request (1000/3000)
77. Deposit response (1100/3100)
7. Deposit response (1100/3100)
88. Deposit response (1100/3100)
8. Deposit response (1100/3100)
After returning a successful 2000 recipient inquiry, do not reject the resulting deposit message except for exceptional conditions such as a system outage.
Prevent Duplicate Deposits
Use transaction date (8) + institution code (8) + transaction number (7) as the unique key. When the same transaction is retransmitted, return a successful response without applying the amount again if the original transaction was already processed.
Deposit Cancellation
- A cancellation may occur only for a deposit made on the same day.
- The cancellation carries the same transaction number as the original deposit.
- Process cancellations idempotently by checking both the original and the existing cancellation state.
- A system cancellation has already been completed by the bank and must be reflected regardless of the client institution's response.
Recipient-Inquiry Agency and Transaction Agency
| Model | Recipient Inquiry | Customer-Cancellation Decision |
|---|---|---|
| Recipient-inquiry agency | Hecto Financial performs the inquiry | Determined by the client institution's cancellation response |
| Transaction agency | Hecto Financial performs both inquiry and deposit handling | Hecto Financial processes cancellation under delegated authority |
A bank-completed system cancellation must be reflected regardless of the agency model.
Remittance Flow
Client Institution
Hecto Financial
Bank
11. Holder-name inquiry (2001, optional)
1. Holder-name inquiry (2001, optional)
22. Forward inquiry
2. Forward inquiry
33. Inquiry response (2101)
3. Inquiry response (2101)
44. Return holder name
4. Return holder name
55. Remittance request (6010)
5. Remittance request (6010)
66. Forward remittance
6. Forward remittance
77. Remittance response (6110)
7. Remittance response (6110)
88. Return remittance result
8. Return remittance result
Remittance supports direct bank contracts and a resale model. In the resale model, the client institution pre-funds a designated deposit account and can remit only within the available balance.
Retrying a Timed-Out Remittance
A timeout may mean the bank completed the transaction but its response was lost. On the same day, resend the original message with the same user transaction number to determine the result. Do not create a new remittance.
Operations
8xxxoperations-management messages are exchanged only between banks and Hecto Financial.- Hecto Financial sends the previous-day reconciliation at approximately 00:35.
- A client institution may implement an on-demand
7000reconciliation request. - Institutions enabled through a separate agreement may use test-call messages to check connectivity.
Next Steps
- Review Communication and Message Format.
- Implement Common Header parsing once.
- Implement each required operation body and response-code policy.
- Test successful, duplicate, timeout, and system-cancellation scenarios.
Need technical support?
Code Samples
HectoFinancial GitHub