Create a virtual account

📘
Check to see if your bank’s product supports the Virtual Accounts API or the Internal Account API in our Virtual Accounts Overview.
If your bank provides balances for these virtual accounts, use the Internal Account API.

Account Number Scheme

Depending on the bank, the virtual account numbers you use will follow a different provisioning scheme:

Bank	Product Name	Scheme
BankProv	Virtual Ledgers	Dynamic
Cross River Bank	Subledgers	Dynamic
Evolve	vAccounts	Range
Goldman Sachs	Virtual Accounts	Range
Increase	Account Numbers	Dynamic
JP Morgan Chase	Virtual Reference Numbers	Range
Silicon Valley Bank	ACH Sub-Accounts	Range
Wells Fargo	Perfect Receivables	Range

A Dynamic virtual account number scheme means the bank determines the virtual account number on request. You do not provide the virtual account number in your API call.

A Range virtual account number scheme means the bank provisions a range of account numbers to use.

You may either omit the account number or provide one when you initiate an API call to create a virtual account. If you omit the account number, Modern Treasury will automatically select one for you.

Creating Virtual Accounts

You can create Virtual Account with or without an account number:

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/virtual_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Funds on behalf of Alice Jones",
    "internal_account_id": "c743edb7-4059-496a-94b8-06fc081156fd",
    "account_details": [
      {
        "account_number": "2000001",
        "account_number_type": "other"
      }
    ]
  }'

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/virtual_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Funds on behalf of Alice Jones",
    "internal_account_id": "c743edb7-4059-496a-94b8-06fc081156fd"
  }'

The response will contain the virtual account, including the virtual account number and routing number.

{
  "id": "2e0296c1-1daf-4b3e-954d-fb9ec7be56f6",
  "object": "virtual_account",
  "name": "Funds on behalf of Alice Jones",
  "description": null,
  "active": true,
  "counterparty_id": null,
  "internal_account_id": "c743edb7-4059-496a-94b8-06fc081156fd",
  "debit_ledger_account_id": null,
  "credit_ledger_account_id": null,
  "account_details": [
    {
      "id": "5668c0cf-972d-49c6-970f-b32591f3e8a6",
      "object": "account_detail",
      "account_number_safe": "0001",
      "account_number_type": "other"
    }
  ],
    "routing_details": [
    {
      "id":"5ceb251f-0235-48a2-81cb-0c668f5ee81b",
      "object": "routing_detail",
      "payment_type": null,
      "routing_number": "121141822",
      "routing_number_type": "aba",
      "bank_name": "BANK OF AMERICA CALIFORNIA, NA",
      "bank_address": {
        "id": "2f1e12dd-de80-44aa-92cd-f0e4101b8e54",
        "object": "address",
        "line1": "PO BOX 27025",
        "line2": null,
        "locality": "RICHMOND",
        "region": "VA",
        "postal_code": "23261-7025",
        "country": "US",
        "live_mode": true,
        "created_at": "2019-11-09T00:11:07Z",
        "updated_at": "2019-11-09T00:11:07Z"
      },
      "live_mode": true,      
      "created_at": "2019-11-09T00:11:07Z",
      "updated_at": "2019-11-09T00:11:07Z"
    }
  ],
  "metadata": {},
  "live_mode": true,
  "created_at": "2020-11-09T00:11:07Z",
  "updated_at": "2020-11-09T00:11:07Z"
}

Creating Virtual Accounts with a Counterparty

Our API supports linking a virtual account to a counterparty. This may be helpful if you are holding funds on behalf of someone, or if you want to link a set of transactions to a counterparty.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/virtual_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Funds on behalf of Alice Jones",
    "internal_account_id": "c743edb7-4059-496a-94b8-06fc081156fd",
    "counterparty_id": "b4313c66-3892-416d-995f-f5b6044b5c7a",
    "account_details": [
      {
        "account_number": "2000001",
        "account_number_type": "other"
      }
    ]
  }'

Creating Virtual Accounts with a Ledger

To automatically track a balance for a Virtual Account, you can link it to two Ledger Accounts: one debit normal account representing your internal account balance and one credit normal account representing the user's wallet balance. If a specific user sends money to their virtual account, both of these balances will automatically increase.

A virtual account can be linked on creation to ledger accounts using the debit_ledger_account_id and credit_ledger_account_id fields. Both fields must be passed together. When a payment moves money into a virtual account, we create an Incoming Payment Details as well as a Ledger Transaction referring to the Incoming Payment Detail via the ledgerable_type and ledgerable_id fields.

When money enters the virtual account, the ledger account referred to by debit_ledger_account_id will be debited and the ledger account referred to be credit_ledger_account_id will be credited.