Guides/Create Virtual Account

Create Virtual Account

Virtual Accounts are unique account numbers assigned to each beneficiary, enabling you to receive deposits and automatically map incoming funds to the correct beneficiary.

These accounts are created along with the beneficiary by including additional fields in the beneficiary creation request.

🧠 Why Virtual Accounts?

Assign dedicated deposit instructions per beneficiary
Automatically reconcile incoming deposits
Identify deposit source using Virtual Account identifier

⚙️ How It Works

Create a beneficiary with virtual account details
FVBank generates a virtual account number + deposit instructions
Share deposit instructions from get transaction details endpoint with your beneficiary
When funds are received:
- A transaction is created
- A Virtual Account identifier is included
Use this identifier to map deposits to the correct beneficiary

🏗️ Create Virtual Account (Node.js)

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
async function createVirtualAccount() {
  try {
    const response = await axios.post(
      `${baseUrl}/beneficiary/create`,
      [
        { "field": "Beneficiary_Type", "value": "individual" },
        { "field": "Beneficiary_Email", "value": "john@fvbank.us" },
        { "field": "Beneficiary_Address", "value": "1437 VIP Road" },
  …

🔍 Get Beneficiary Details (Deposit Instructions)

After creating the virtual account, fetch beneficiary details to retrieve deposit instructions:

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
// 🔁 Replace with actual Beneficiary ID
const beneficiaryId = "your_beneficiary_id";
async function getBeneficiaryDetails() {
  try {
    const response = await axios.get(
      `${baseUrl}/beneficiary/details/${beneficiaryId}`,
      {
        headers: {
  …

📦 Example Response (Virtual Account & Deposit Instructions)

code


{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "CreatedBy": "Zomato - Rishav",
    "CreatedOn": "2025-07-10T09:05:16.431-04:00",
    "BeneficiaryId": "-1654055480350822652",
    "Available_Payments_Type": [],
    "Beneficiary_Type": "Individual",
    "Beneficiary_Name": "Varun 1 Upadhayay 2",
    "Beneficiary_First_Name": "Varun 1",
  …

📥 Deposit Flow with Virtual Accounts

Share deposit instructions with your beneficiary
Beneficiary sends funds to assigned virtual account
FVBank creates a deposit transaction
Transaction webhook includes:

code


{
  "label": "Virtual Account",
  "value": "780008000006"
}

🔔 Webhook Mapping

In deposit webhooks, the Virtual Account field is included in AdditionalData.

This allows you to:

Identify which beneficiary the deposit belongs to
Automatically reconcile funds
Avoid manual mapping

⚡ Best Practices

Always store Beneficiary ID ↔ Virtual Account mapping
Use webhooks for real-time deposit tracking
Validate documents (Front_Document, Back_Document) before submission, refer to upload file endpoint to understand how to upload file for these fields

📌 Summary

code


virtual-account-summary"
Create Beneficiary (with VA) → Get Deposit Instructions → Share with User → Receive Deposit → Map via Virtual Account

Virtual Accounts enable automated, scalable, and error-free deposit reconciliation.

Related endpoints