Create a Virtual Account
TxB APIs allow Clients to create and modify new virtual accounts, which act as subledgers underneath an existing (virtual-enabled) commercial deposit account. Clients can use this flexible ledger tool to better track and allocate money movement without the latency and manual work usually involved in opening commercial deposit accounts via a graphical interface. Virtual accounts can be assigned to individual customers, suppliers, deals, or anything else Clients might want to track at a granular level.
For additional context on the account and service types we provide, read more here.
Step by Step Guide
Step 1 - Retrieve a list of existing accounts / products
In order to create a virtual account, you must link it with a parentAccount when opening. Virtual accounts are bound to and inherit the currency, branchCountry and ownershipAndControl details from the parentAccount.
So, the first step is to retrieve all of your existing products and their account numbers. These include deposit accounts (physical and virtual), financing accounts and payments only accounts.
GET /v2/products returns:
{
"productList": [
{
"productType": "DEPOSIT_ACCOUNT",
"relatedEntities": [
{
"entityId": "3899CF77860848BE8D89F2F70FA2F4ED",
"roleType": "DEPOSITOR"
}
],
"productTypeSpecificData": {
"depositAccountSpecificData": {
"accountNumber": "220000008400",
"accountObject": {
"linkUrl": "https://api.test.txb.gs.com/v2/accounts/220000004004"
},
"transactionData": [
{ ... }
]
}
}
},
{
"productType": "DEPOSIT_ACCOUNT",
"relatedEntities": [
{
"entityId": "3899CF77860848BE8D89F2F70FA2F4ED",
"roleType": "DEPOSITOR"
}
],
"productTypeSpecificData": {
"depositAccountSpecificData": {
"accountNumber": "110000008260",
"accountObject": {
"linkUrl": "https://api.test.txb.gs.com/v2/accounts/11008260"
},
"transactionData": [
{ ... }
]
}
}
}
]
}
Step 2 - Identify the physical account under which you'll create the virtual account
Once you have your product list response (from step 1), get the account types by looking at each account detail.
GET /v2/accounts/220000008400 returns:
{
"type": "PHYSICAL_DEPOSIT", //Identifies account type
"accountStatus": "ACTIVE",
"accountCurrency": "USD", // All linked virtual accounts will inherit this
"rate": null,
"branchCountry": "US", // All linked virtual accounts will inherit this
"administrative": {
"openDate": "2022-03-15T15:49:24.845Z",
"accountName": "My First Account",
"accountNickname": "Main USD Account"
...
}
...
}Repeat this step for each of your products to identify accounts with the desired attributes.
{
"type": "PHYSICAL_DEPOSIT",
"accountStatus": "ACTIVE",
"accountCurrency": "GBP", // All linked virtual accounts will inherit this
"rate": null,
"branchCountry": "US",
"administrative": {
"openDate": "2022-03-19T19:49:24.845Z",
"accountName": "My Second Account",
"accountNickname": "Main GBP Account"
...
}
...
}Step 3 - Select which virtual account to activate
Now that you have your list of parentAccounts, you retrieve a pre-reserved set of account numbers. Couple things to note:
- Your query can be filtered by
branchCountryas a query parameter - Accounts with
branchCountry= US will return 12 digit account numbers, without any IBANs or Bank Identifiers - Accounts with
branchCountry= GB will return account numbers, IBANs and Bank Identifiers. This is important because in the UK, accountNumbers are not unique. But accountNumbers + sort codes are unique
GET /v2/accounts/reserved returns:
{
"reservedAccountNumbers": [
{
"accountNumber": "80001319",
"iban": "GB74GSLD04296280001319", // only applicable for non-US accounts
"bankIdentifier": { // only applicable for non-US accounts
"bic": "GSLDGB20",
"routingInfo": { //Required to open branchCountry = GB accounts
"code": "GBDSC",
"value": "042962"
}
},
"externalPaymentIds": null
},
{
"accountNumber": "800400123987",
"iban": null,
"externalPaymentIds": null
},
{
"accountNumber": "800400333444",
"iban": null,
"externalPaymentIds": null
},
...
]
"hasMore": false
}Step 4 - Create a virtual account
You can now send the request to open a virtual account using the reserved accountNumber (from Step 3) and the parentAccountNumber of your physical account (from Step 2).
POST /v2/accounts/virtual with this payload:
{
"virtualAccountRequest": {
"requestId": "VIAOpeningUSD",
"administrative": {
"accountName": "ClientVIAUSD",
"accountNickname": "USD VIA",
"depositorType": "WHOLESALE",
"accountPurposes": [
"COMMERCIAL_PAYMENTS"
]
},
"accountIdentifiers": {
"accountNumber": "800400123987" // The account number from your reserved list
},
"ownershipAndControl": {
"thirdPartyIndicator": false,
// This value is true if the virtual account will be used by a 3rd party
"depositorEntityId": "F196FF3DAAAF4E939296CCB7808F6E74",
"relatedPersons": [
{
"contactType": "AUTHORIZED_PERSON",
"personId": "person_contact^519397AA4FFF4C3B93E4EC6429ED1E1B"
}
]
},
"typeSpecificInfo": {
"virtualAccountInfo": {
"parentAccountNumber": "220000008400"
// Identifies the physical account your virtual is linked to
}
}
}
}Repeat this step for each of the virtual account currencies you wish to open. Remember to use a new requestId and reserved account number in each request.
POST /v2/accounts/virtual with this payload:
{
"virtualAccountRequest": {
"requestId": "VIAOpeningGBP",
"administrative": {
"accountName": "ClientVIAGBP",
"accountNickname": "USD GBP",
"depositorType": "WHOLESALE",
"accountPurposes": [
"COMMERCIAL_PAYMENTS"
]
},
"accountIdentifiers": {
"accountNumber": "800400333444" // the account number from your reserved list
},
"ownershipAndControl": {
"thirdPartyIndicator": false,
"depositorEntityId": "F196FF3DAAAF4E939296CCB7808F6E74",
"relatedPersons": [
{
"contactType": "AUTHORIZED_PERSON",
"personId": "person_contact^519397AA4FFF4C3B93E4EC6429ED1E1B"
}
]
},
"typeSpecificInfo": {
"virtualAccountInfo": {
"parentAccountNumber": "110000008260"
}
}
}
}Step 5 - Monitor the status of account creation
Using the query parameter of requestType you're able to check both CREATE and UPDATE requests.
GET /v2/accounts/requests/VIAOpeningUSD?requestType=CREATE returns:
{
"accountNumber": "800400123987",
"status": "COMPLETED"
}Step 6 - Verify that account object is now created
Once your account status is COMPLETED, you can now retrieve the details of the account you created. Note that your accounts will contain some attributes which were inherited from the parentAccount.
GET /v1/accounts/223122343243 returns:
{
"type": "VIRTUAL",
"accountStatus": "ACTIVE",
"accountCurrency": "USD",
"rate": null,
"branchCountry": "US",
"admistrative": {
"openDate": "2022-03-15T15:49:24.845Z",
"accountName": "ClientVIAUSD",
"accountNickname": "USD VIA",
...
},
"otherInfo": {
"transactionData": [
{
"linkUrl": "https://api.test.txb.gs.com/v2/reports/transactionReports?referenceNumber=220000004004&businessDate=2022-03-25&limit=15&offset=0" //this will retrieve the latest transactions on the account
}
]
}
}Step 7 - View associated account transactions
Once your account status is COMPLETED, you can now retrieve the details of the account you created. Your accounts should be setup with the specified attributes and inherited other from the parentAccount.payments.
POST v2/reports/transactionReports?referenceNumber=800400123987&businessDate=20222-03-25
{
"asOfDateTime": "2022-03-25T15:48:42.279Z",
"references": {
"referenceNumber": "800400123987",
"referenceName": "ClientVIAUSD",
"referenceBank": {},
"referenceType": "DEPOSITACCOUNT",
"jurisdiction": "US",
"currency": "USD",
"isvirtual": true,
"virtualAccountDetails": {}
},
"balances": [
{
"balanceType": "LEDGER",
"startOfDayBalance": 0,
"currentBalance": 0
}
...
],
"transactions": [
{}
],
"hasMore": false
}Banking as a Service
Clients building an 'embedded banking' solution with TxB (read more) will perform an additional step when opening new virtual accounts on behalf of your end users. Prior to opening a virtual account, you must first create a record of eligibility for your end user. This end user record contains the data TxB needs to confirm eligibility and manage Know Your Customer requirements and other obligations. Learn more by getting in touch.
Originate payments
arrow_forwardLearn how to originate payments and collections requests and then track statuses
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.