Create virtual account

Use case

Here we will review how to set up a virtual account when Tuum is the service provider:

Use case data	API parameters with values
Virtual account type.	"accountTypeCode": "VIRTUAL"
The master account is a currency account with the ID-1279.	"masterAccountId": "ID-1279"
The name of the account holder is Trevor Harry Tuum.	"personName": "Trevor Harry Tuum"
Trevor is assigned to the GROUP_A customer group.	"customerGroupCode": "GROUP_A"
The standard price list is assigned to the account.	"priceListTypeCode": "STANDARD"
Trevor's residency country is the Great Britain.	"residencyCountryCode": "GB"
The virtual account currency is GBP.	"currencyCode": "GBP"
The account is opened with standard setup scheme. And account numbers are generated and assigned by Tuum.	"accountTypeSetupCode": "STANDARD"
Tuum is the service provider.	"serviceProviderCode": "TUUM"

Virtual account setup requires reference to the master account id.

Sample API call

To create a virtual account, make the following API call.

https://account-api.sandbox.tuumplatform.com/api/v4/persons/{personId}/account

See more about the create account endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for creating an account.

JSON

{
  "accountTypeCode": "VIRTUAL",
  "masterAccountId": "ID-1279",
  "personName": "Trevor Harry Tuum",
  "residencyCountryCode": "GB",
  "customerGroupCode": "GROUP_A",
  "priceListTypeCode": "STANDARD",
  "currencyCode": "GBP",
  "accountTypeSetupCode": "STANDARD",
  "serviceProviderCode": "TUUM"
}

cURL

curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3392/accounts' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMjZUMTk6MDU6MDgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODc4MDYzMDh9.iySF4SAjJzd6j5-KGeiZ-JYP3fIAnLZUkUjyhiTTsbM' \
-H 'Content-Type: application/json' \
-d '{
  "accountTypeCode": "VIRTUAL",
  "masterAccountId": "ID-1279",
  "personName": "Trevor Harry Tuum",
  "residencyCountryCode": "GB",
  "customerGroupCode": "GROUP_A",
  "priceListTypeCode": "STANDARD",
  "currencyCode": "GBP",
  "accountTypeSetupCode": "STANDARD",
  "serviceProviderCode": "TUUM"
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "accountId": "ID-1283",
        "personId": "ID-3392",
        "accountTypeCode": "VIRTUAL",
        "activationDate": "2023-06-26",
        "accountName": null,
        "personName": "Trevor Harry Tuum",
        "statusCode": "ACTIVE",
        "iban": "GB05XXXX04030100000462",
        "bic": "LHVBGB2LXXX",
        "defaultCurrencyCode": "GBP",
        "tenantCode": "MB",
        "residencyCode": "GB",
        "customerGroupCode": "GROUP_A",
        "personTypeCode": null,
        "intraOrgCode": null,
        "accountTypeSetupCode": "STANDARD",
        "serviceProviderCode": "TUUM",
        "interestMethodAssignmentCode": null,
        "accountClassCode": null,
        "balances": [],
        "masterAccountId": "ID-1279",
        "accountNumbers": [
            {
                "accountNumber": {
                    "value": "00000462",
                    "type": "BBAN"
                },
                "countryCode": "GB",
                "financialInstitutionId": {
                    "value": "040301",
                    "type": "SORT_CODE"
                },
                "defaultCurrencyCode": "GBP",
                "accountNumberId": "ID-1144",
                "accountId": "ID-1283",
                "financialInstitutionIdTypeCode": null,
                "statusCode": "ENABLED"
            }
        ],
        "taxResidencyCountryCode": "GB",
        "jurisdictionCountryCode": "GB"
    }
}

Result

The outcome of the API call is the complete set of account data. Including the parameters generated by the Tuum system:

Parameter and value	Explanation
"accountId": "ID-1283"	A unique identifier is assigned to the new account.
"statusCode": "ACTIVE"	The new account is created and activated.
"iban": "GB05XXXX04030100000462"	The IBAN assigned to the new account.
"bic": "LHVBGB2LXXX"	The BIC assigned to the new account.