Create a Virtual Account
Guide for creating 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.
Updated 6 months ago