Wallet, currency, and VAN user guide

Multicurrency wallet or account

Every account holder gets a wallet in multiple currencies. You can consider a wallet an account, so you can use the term wallet or account interchangeably. A wallet holds balances in all the currencies that the program configures. 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. In the diagram, for example, the wallet has balances in three currencies.

Virtual account number (VAN)

Nium has integrations with key banking partners to help you obtain and assign multiple virtual bank account numbers to meet your product needs. The Nium One platform helps you to assign a Virtual Account Number (VAN) to collect locally or use the Society for Worldwide Interbank Financial Telecommunications (SWIFT). You can assign a USD local VAN, for example, so the account holder can collect or fund using the USD VAN (local) using US ACH rails. Nium can help you use the right VAN source. Similarly, to collect locally, in GBP using UK FPS rails, Nium can help assign a local GBP-enabled VAN.

📘
What's a virtual bank account? What's 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 that a bank offers to help the account holder get multiple account numbers all linked to the primary real bank account. This feature helps the account holder to receive money using multiple virtual account numbers and reconcile effectively. So, virtual bank accounts aren't separate accounts but are proxy accounts or are linked to the underlying primary real main bank account.

See the following picture.

The picture captures a high-level program structure. It has a Banking As a Service (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 multicurrency wallet. The zoom-in of one of the multicurrency wallets (account holder-n) shows the wallet has two currencies and each of the currencies has its own VAN.

Nium supports assigning VANs at underlying multicurrency wallets and at client prefund accounts, as illustrated in the picture. As a first step to making use of the VAN feature, you need to work with Nium to configure the client program with the appropriate set of VAN sources. In the picture above, the client program is configured with USD VAN and GBP VAN (using the right USD VAN Source and GBP VAN Source). These configuration details about the VAN source are 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, the following code shows only a select section of the API response.

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

The response suggests that the given client program is configured to make use of JPM VAN 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 currencies). 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, or sort code details relevant to the VAN source to you, and that's not part of the API response. You need to make use of that code, along with the account number, to receive funds through bank rails into the client prefund account. In the above example, for instance, the SWIFT code is CHASSGSG and you need to use this code along with the account number 20024397659 to receive funds into either one of the client prefund accounts.

Nium One supports assigning VANs at the individual currency of the account holder’s multicurrency wallet or account. You see in the picture that a VAN could be assigned to the USD currency and GBP currency of the wallet. So, every currency within every wallet could be assigned a unique VAN.

There are two ways in which the VANs can be assigned at the multicurrency wallet level, under each account holder.

Automatically

As part of the client configuration, Nium can configure the VAN sources that need to be used to assign a VAN for a given currency within the wallet. Then Nium lets the platform auto-assign the VAN at the currency level automatically when the customer record gets created. Along with the customer record, the platform also creates a multicurrency wallet. During this customer wallet creation stage, the platform can automatically assign a VAN at the currency level.

Nium can configure the SGD currency, for example, to make use of a certain bank-VAN-source so that during the customer or wallet creation, the platform automatically assigns an SGD VAN from the configured bank-VAN source to the SGD currency of the wallet.

On demand

By using the “Assign Payment Id“ API function, you, the BaaS client, can assign the VAN from one of the configured VAN sources. These are 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 does this configuration for you. To know the list of VAN sources configured in your client configuration, make use of the Get Client Details API function.

You can use the Get Customer Details API function to know about the VANs assigned to the account holder’s multicurrency 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 appears.

{
  ...
    "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. The bankName data element indicates the VAN source used. Nium can help you with the appropriate bank code or SWIFT code for the configured banks. In this case, the SWIFT code to be used would be CHASSGSG. So, this particular account holder collects funds into the USD or GBP account by using the SWIFT code CHASSGSG and bank account number 20024397576.

Multicurrency wallet or account

Virtual account number (VAN)

📘What's a virtual bank account? What's the difference between a real bank account and a virtual bank account?

📘
What's a virtual bank account? What's the difference between a real bank account and a virtual bank account?