menu

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 branchCountry as 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.


Certain solutions and Institutional Services described herein are provided via our Marquee platform. The Marquee platform is for institutional and professional clients only. This site is for informational purposes only and does not constitute an offer to provide the Marquee platform services described, nor an offer to sell, or the solicitation of an offer to buy, any security. Some of the services and products described herein may not be available in certain jurisdictions or to certain types of clients. Please contact your Goldman Sachs sales representative with any questions. Any data or market information presented on the site is solely for illustrative purposes. There is no representation that any transaction can or could have been effected on such terms or at such prices. Please see https://www.goldmansachs.com/disclaimer/sec-div-disclaimers-for-electronic-comms.html for additional information.
Transaction Banking services are offered by Goldman Sachs Bank USA (“GS Bank”). GS Bank is a New York State chartered bank, a member of the Federal Reserve System and a Member FDIC.
GS DAP™ is owned and operated by Goldman Sachs. This site is for informational purposes only and does not constitute an offer to provide, or the solicitation of an offer to provide access to or use of GS DAP™. Any subsequent commitment by Goldman Sachs to provide access to and / or use of GS DAP™ would be subject to various conditions, including, amongst others, (i) satisfactory determination and legal review of the structure of any potential product or activity, (ii) receipt of all internal and external approvals (including potentially regulatory approvals); (iii) execution of any relevant documentation in a form satisfactory to Goldman Sachs; and (iv) completion of any relevant system / technology / platform build or adaptation required or desired to support the structure of any potential product or activity.
Mosaic is a service mark of Goldman Sachs & Co. LLC. This service is made available in the United States by Goldman Sachs & Co. LLC and outside of the United States by Goldman Sachs International, or its local affiliates in accordance with applicable law and regulations. Goldman Sachs International and Goldman Sachs & Co. LLC are the distributors of the Goldman Sachs Funds. Depending upon the jurisdiction in which you are located, transactions in non-Goldman Sachs money market funds are affected by either Goldman Sachs & Co. LLC, a member of FINRA, SIPC and NYSE, or Goldman Sachs International. For additional information contact your Goldman Sachs representative. Goldman Sachs & Co. LLC, Goldman Sachs International, Goldman Sachs Liquidity Solutions, Goldman Sachs Asset Management, L.P., and the Goldman Sachs funds available through Goldman Sachs Liquidity Solutions and other affiliated entities, are under the common control of the Goldman Sachs Group, Inc.
© 2024 Goldman Sachs. All rights reserved.