Create a multi-currency account
TxB APIs allow clients to create multi-currency accounts, which is a single account number associated with virtual accounts denominated in multiple currencies.
Multi-currency accounts allow for payments/receipts and reporting to be consolidated to a single account number, rather than having an account per currency.
Clients can use this flexible ledger tool to better track and allocate money movement in an automated manner which helps streamline processes.
With account opening through APIs, clients are able to improve process efficiency and reduce manual effort.
Step by step guide
Step 1 - Reserve a list of accounts
The first step in multi-currency account creation, retrieving a pre-reserved set of account numbers. Your query can be filtered by branchCountry as a query parameter.
For clients in the United States, this will return 12-digit account numbers without any IBANs or bank identifiers. For clients outside of the United States, this will return account numbers, IBANs and bank identifier information. The reason for this is that the account number is only unique when coupled with the routingInfo key value pair.
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": {
"code": "GBDSC",
"value": "042962"
},
(...)
},
(...)
},
{
"accountNumber": "800400123987",
"iban": null,
...
},Step 2 - Create a multi-currency account
Next you should use an account from the reserved response to open a multi-currency account. When opening an account for a non-US client, you must include the routingInfo provided.
POST /v2/accounts/MULTI_CURRENCY with this payload:
{
"multiCurrencyAccountRequest": {
"requestId": "MCAOpening1",
"branchCountry": GB
"administrative": {
"accountName": "My First MCA ",
"accountNickname": "MCA 1",
"accountPurposes": [
"COMMERCIAL_PAYMENTS"
]
},
"accountIdentifiers": {
"accountNumber": "80001319", // the account number from your reserved list
"bankIdentifier": { // the routingInfo from your reserved list
"routingInfo": {
"code": "GBDSC",
"value": "042962"
}
},
"ownershipAndControl": {
(...)
},
}Step 3 - Monitor the status of an account request
To monitor the status of a request you can use the requests endpoint. Using the query parameter of requestType you’re able to check both CREATE and UPDATE requests.
GET /v2/accounts/requests/MCAOpening1?requestType=CREATE returns:
{
"accountNumber": "80001319",
"status": "COMPLETED"
}Step 4 - Verify account creation
You can retrieve the details of the account you created.
GET /v2/accounts/80001319 returns:
{
"type": "MULTI_CURRENCY",
"accountStatus": "ACTIVE",
"accountCurrency": null,
"rate": null,
"branchCountry": GB,
"admistrative”:
"openDate": "2022-03-15T15:49:24.845Z",
"accountName": "My First MCA",
"accountNickname": "MCA 1",
...
}Step 5 – Create virtual accounts for each currency
You can open underlying currency accounts for your multi-currency account. This is achieved by creating a virtual account linked to a physical account of the same currency. In addition to the aforementioned parent account linkage, you must also include a multi-currency account linkage.
Opening your linked currency accounts is the same process as opening a virtual account with the additional linkage.
For example, to enable EUR for your MCA then you must open a virtual account with a EUR parent account.
POST /v2/accounts/VIRTUAL with this payload:
{
"virtualAccountRequest": {
"requestId": "VIAOpeningForMCA",
"administrative": {
"accountName": "My EUR VIA",
"accountNickname": "EUR VIA",
"depositorType": "WHOLESALE",
"accountPurposes": [
"COMMERCIAL_PAYMENTS"
]
},
"accountIdentifiers": {
"accountNumber": "80001320" // the account number from your reserved list
"bankIdentifier": { // the routingInfo from your reserved list
"routingInfo": {
"code": "GBDSC",
"value": "042962"
}
},
"ownershipAndControl": {
(...)
},
"typeSpecificInfo": {
"virtualAccountInfo": {
"parentAccountNumber": "010109780" // the physical account with currency EUR
"multiCurrencyAccountNumber": "80001319" //multi-currency account opened above
}
}
}
}To enable USD for your MCA then open a virtual account with a USD parent account.
{
"virtualAccountRequest": {
"requestId": "VIAOpeningForMCA2",
"administrative": {
"accountName": "MY USD VIA",
"accountNickname": "USD VIA",
"depositorType": "WHOLESALE",
"accountPurposes": [
"COMMERCIAL_PAYMENTS"
]
},
"accountIdentifiers": {
"accountNumber": "80001321", // the account number from your reserved list
"bankIdentifier": { // the routingInfo from your reserved list
"routingInfo": {
"code": "GBDSC",
"value": "042962"
}
},
"ownershipAndControl": {
"thirdPartyIndicator": true // true where depositor entity differs from parent account
"depositorEntity": "F196FF3DAAAF4E939296CCB7808F6E74",
"relatedPerson": "person_contact^519397AA4FFF4C3B93E4EC6429ED1E1B"
},
"typeSpecificInfo": {
"virtualAccountInfo": {
"parentAccountNumber": "010108400", // the physical account with currency USD
"multiCurrencyAccountNumber": "80001319" // multi-currency account opened above
}
}
}
}Step 6 – View your currency enabled MCA
Once your virtual accounts have been created then you can now begin to transact on your MCA in those currencies. To view the currencies associated to your MCA you can review the account by repeating step 4.
GET /v2/accounts/80001319 returns:
{
"type": "MULTI_CURRENCY",
"accountStatus": "ACTIVE",
"accountCurrency": null,
"rate": null,
"branchCountry": "GB",
"administrative": {
"openDate": "2022-03-15T15:49:24.845Z",
"accountName": "MCA TEST 1",
"accountNickname": "MCA TEST 1",
"depositorType": null,
"accountPurposes": [
"SUPPLIER_OR_VENDOR_MANAGEMENT"
],
"accountPurposeOtherDescription": null
},
"accountIdentifiers": {
"accountNumber": "80001319 ",
"iban": "GB81GSLD04296280001319",
"bankIdentifier": (...)
},
"ownershipAndControl": {
"relatedEntities": [
{
"entityId": "BFE4BF250968487088D86B98F05480C1",
"roleType": "DEPOSITOR"
}
],
"thirdPartyIndicator": true,
"addressId": "Address^28E45539E779326E92DD7F581B644CC1",
"relatedPersons": [
{
"personId": "ContactDetail^4F54B56F64973FD699185C5A0EBC5B24",
"contactType": "AUTHORIZED_PERSON" },
]
},
"otherInfo": {
"dacaInfo": null,
"transactionData": [
{
"linkUrl": "https://api.uat.txb.gs.com/v2/reports/transactionReports?referenceNumber=80001320&businessDate=2022-05-25&limit=15&offset=0"
},
{
"linkUrl": "https://api.uat.txb.gs.com/v2/reports/transactionReports?referenceNumber=80001321&businessDate=2022-05-25&limit=15&offset=0"
}
]
},
"typeSpecificInfo": {
"physicalDepositAccountInfo": null,
"virtualAccountInfo": null,
"multiCurrencyAccountInfo": {
"currenciesSupported": [ // the linked VIA currencies are listed here
"EUR"
"USD"
]
},
"termAccountInfo": null
}
}Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.