Wallet, Multi-Currency, Virtual Account Numbers

Multi-Currency Wallet (Account)

Every account holder gets a multi-currency wallet. A wallet can be considered an account; so the term wallet or account can be used interchangeably. A wallet can store balances in all the currencies configured in the program. For instance, if the client program is configured to support USD, GBP and EUR currencies, then a given wallet can store balances in USD, GBP and EUR. For instance in the diagram, the wallet has balances in three currencies.

Virtual Account Numbers

Nium has integrations with key banking partners to help you obtain and assign virtual bank account numbers to meet your product needs. Nium platform can help you to assign virtual account numbers that can be used to collect locally or using SWIFT. For example, you could assign a USD local virtual account number (we can advise you of the right VAN source to use) so the account holder can collect or fund using the USD virtual account number (local) using US ACH rails. Similarly to collect locally in GBP using UK FPS rails, Nium could help assign a local GBP enabled Virtual Account Number.

📘

What is a virtual bank account? What is the difference between a real bank account and a virtual bank account?

A real bank account is held in the name of the account holder in the books of the bank. Whereas a virtual bank account is a feature offered by banks to help the account holder get multiple account numbers all linked to the primary real bank account. This feature helps the account holder to provide to receive money using the virtual account numbers and reconcile effectively. So, virtual bank accounts are not really separate accounts but are proxy or linked to the underlying primary real main bank account.

Take a look at the following picture.

4388

The picture captures a high level BaaS Program Structure. It has a BaaS Client with two client level prefund accounts (GBP and USD). The client also has a certain number of account holders and each of these account holders has its own multi-currency wallet. The zoom-in of one of the multi-currency wallet (account holder-n) shows the wallet has two currencies and each of the currencies has its own Virtual Account Number.

Nium Platform supports assigning Virtual Account Numbers at underlying multi-currency wallets and at client prefund accounts, as illustrated in the picture. As a first step to make use of the Virtual Account Number feature, you need to work with Nium to configure the client-program with the appropriate set of Virtual Account Number sources. In the picture above, the client program was configured with USD VAN and GBP VAN (using the right USD VAN Source and GBP VAN Source). This configuration details about the VAN Source configured can be seen in the Get Client Details API response

curl --location --request GET '<https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078>'  \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

For brevity, only a select section of the API response is shown below.

{
  ...
  "paymentIds": [
    {
      "currencyCode": "GBP",
      "uniquePayerId": null,
      "uniquePaymentId": "20024397659",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "USD",
      "uniquePayerId": null,
      "uniquePaymentId": "20024397659",
      "bankName": "JPM_SG"
    }
  ],
  ...
}

The above response suggests that the given client-program is configured to make use of JPM Virtual Account Number Source to issue USD VAN and SGD VAN. The specific bank account number assigned to the Client Prefund Account - for USD: 20024397659 and for SGD: 20024397659 (same account number, as this VAN happens to support multiple currency). The data element ‘bank_name’ is to be seen as the VAN Source. Depending on the configuration you agree with Nium, this VAN Source could change. Nium can share the SWIFT Code/Bank Code/Sort Code details relevant for the VAN Source to you, and that is not part of the API response. You will need to make use of that code along with the account number to receive funds through bank rails into the client prefund account. For instance - in the above example, the SWIFT Code is CHASSGSG, and you will need to use this code along with the account number 20024397659 to receive funds in to either one of the client prefund accounts.

As called out above, Nium Platform supports assigning Virtual Account Numbers at the individual currency of the account holder’s multi-currency wallet (account). So in the above picture, virtual account number could be assigned to USD currency and GBP currency of the wallet. So, every currency within every wallet could be assigned with a unique virtual account number.

There are two ways in which the Virtual Account Numbers can be assigned at the multi-currency wallet level (under each account holder).

  1. Automatically

As part of the client configuration, we could configure the VAN Sources that need to be used to assign Virtual Account Number for a given currency within the wallet and let the platform to auto-assign the VAN at the currency level automatically when the customer record gets created. Along with the customer record, the platform also creates the multi-currency wallet so during this customer, wallet creation stage the platform can automatically assign VAN at the currency level.

For example - we could configure SGD currency to make use of a certain bank-VAN-source; so during customer/wallet creation, the platform will automatically assign an SGD VAN from the configured bank-VAN-source to the SGD currency of the wallet.

  1. On demand

By using the “Assign Payment Id“ API function, you (BaaS Client) can assign the Virtual Account Number from one of the configured VAN Sources (configured as part of the BaaS Client configuration). Before using this API function, make sure to configure the list of VAN Sources in your client-configuration (Nium will do this configuration for you). To know the list of VAN sources configured in your client configuration, please make use of Get Client Details API function.

You can use Get Customer Details API function to know about the Virtual Account Numbers assigned to the account holder’s multi-currency wallet (at each currency level).

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/59796fed-48d3-4d36-8915-0ff1a83d0bd0' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

For brevity, only a select section of the API response is shown below.

{
  ...
    "paymentIds": [
        {
            "currencyCode": "GBP",
            "uniquePaymentId": "20024397576",
            "uniquePayerId": null,
            "bankName": "JPM_SG"
        },
        {
            "currencyCode": "USD",
            "uniquePaymentId": "20024397576",
            "uniquePayerId": null,
            "bankName": "JPM_SG"
        }
    ],
  ...
}

The uniquePaymentId is the bank account number. bankName data element indicates the Virtual Account Number (VAN) source used. Nium can help you with the appropriate bank code/SWIFT Code for the configured banks. In this case, the SWIFT Code to be used would be CHASSGSG. So, this particular account holder to collect funds into the USD/GBP account by using the SWIFT Code CHASSGSG and bank account number 20024397576.