---
title: "New Virtual Account"
method: POST
path: "/virtual-account"
tags: ["Virtual Account (VA)"]
---

# New Virtual Account

`POST /virtual-account`

## Request

- Base URL: `https://api.finmo.net/v1`
- URL: `https://api.finmo.net/v1/virtual-account`
- Auth: HTTP basic

Create a Virtual Account for an existing customer. Virtual Account is a Bank account number issued to a Finmo Wallet. The Virtual account can receive funds from any bank using the bank’s own tools.

Merchants who wish to enable the Virtual Account creation should contact the Finmo support team at support@finmo.net, and we will review your request promptly. Please ensure to use your registered email and include your organization ID in the email.

Virtual accounts can be classified into two types:

1.  **Static VA:** As the name suggests, Static VAs are fixed and function like a regular bank accounts. Once issued, they can be reused indefinitely for multiple transactions. There are no restrictions on the amount that can be transferred to a Static VA.
  
2.  **Dynamic VA:** Dynamic VAs are generated for specific transactions, with each account number being unique to a particular purpose and amount. While beneficial for reconciliation, Dynamic VAs can be somewhat inconvenient for consumers, as they must transfer funds to a new account number for each transaction. Additionally, some banks may impose restrictions on the amount or have a waiting period for newly added beneficiaries. Finmo supports both types of VAs depending on the market.
  

### Virtual Accounts in Various Markets

*   **Australia:** Virtual Accounts can be issued in the form of a BSB and Account Number, a static PayID, or an account proxy, e.g., ```customer_username@myfiatwallet.com```.
  
*   **Singapore:** Virtual Accounts are issued solely as Account Numbers.
  
*   **EU and UK:** Virtual Accounts are issued as IBANs.
  
*   **Indonesia:** Virtual Accounts are issued as account numbers, where the first six digits identify the issuing bank. Dynamic VAs are especially popular in Indonesia, with 80-90% of eCommerce transactions conducted via Dynamic VAs.
  

### Popular Use-cases

*   **Remittances:** Generate a Virtual Account and issue it to customers who frequently transfer funds. This way, customers do not need to change account numbers for each transfer.
  
*   **Fiat or Digital Currency Wallet Top-ups:** Issue a VA to wallet users, allowing them to easily load funds and transact on your platform.

## Request body

- object
  - `currency` string, required: VA currency
  - `customer_id` string, required: Customer reference (customer_*)
  - `scope` 'CUSTOMER' | 'MASTER': Scope of the VA, can be "CUSTOMER" or "MASTER"
  - `credit_wallet_id` string, required: **Conditionally required:** Either credit_wallet_id or credit_wallet_category should be present. Wallet ID is needed when a customer is linked to more than one wallet. If you pass a customer_id and its linked to a customer wallet, all funds are deposited there. But if the customer_id is linked to your Organization Payin wallet then you don't need to provide it here. However if you pass both the Customer_id and the wallet_id and both of them are not linked then the API would give an error. If you pass a customer wallet only and nothing in customer_id, API will still work.
  - `credit_wallet_category` 'PAYIN' | 'PAYOUT' | 'FEES' | 'GENERAL', required: **Conditionally required:** Either credit_wallet_id or credit_wallet_category should be present Credit Wallet Category. Category can be "PAYIN", "PAYOUT", "FEES", "GENERAL".
  - `fees_wallet_id` string: Fees Wallet ID
  - `description` string: VA reference or description can be passed
  - `payin_method_name` string, required: Payment method name. If you pass a Payin Method here that does not support the currency you passed, the API will fail
  - `payin_method_param` object: Provide the params required by the Payin method
  - `organization_reference_id` string: A reference you can later use to identify this payment, such as an order number. Can only be alphanumeric and must be unique for Benefit.
  - `webhook_url` string
  - `metadata` object: Custom Data
    - `any-custom-ref` string

## Response `201`

Created

- object
  - `data` object
    - `category` string
    - `created_at` string, date-time
    - `credit_wallet_id` string
    - `currency` string
    - `customer_id` string
    - `deleted_at` string, date-time, nullable
    - `description` string, nullable
    - `expire_at` string, date-time, nullable
    - `expired_at` string, date-time, nullable
    - `fees_currency` string
    - `fees_including_tax` number
    - `fees_without_tax` number
    - `is_active` boolean
    - `is_cancellable` boolean
    - `is_chargeable` boolean
    - `is_deleted` boolean
    - `is_expired` boolean
    - `is_fees_charged` boolean
    - `is_refundable` boolean
    - `metadata` object
      - `any-custom-ref` string
    - `org_id` string
    - `organization_reference_id` string
    - `pay_code` object
      - `text` string
    - `payin_method_name` string
    - `payin_method_param` object
      - `payid_reference` string
    - `scope` 'CUSTOMER' | 'MASTER'
    - `tax_on_fees` number
    - `transaction_id` string
    - `updated_at` string, date-time
    - `virtual_account_id` string
    - `webhook_url` string, uri, nullable
  - `request_id` string
  - `request_time` string, date-time
  - `status_code` integer
  - `status_text` string
  - `success` boolean

## Other responses

- `400`: Bad Request
- `404`: Not Found

## Changes

- **2026-11-03** `39e5e5ab5c3a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/virtual-account/post.md)

---

[API](https://skmtc.dev/finmo/apis/finmo-api.md) - [All operations](https://skmtc.dev/finmo/apis/finmo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/finmo/apis/finmo-api/revisions/39e5e5ab5c3a?raw)