Wallet, currency, and VAN

Multicurrency wallet or account

Your customers or account holders get a wallet in multiple currencies. You can consider a wallet an account, so you can use the term wallet or account interchangeably. The wallet holds balances in all the currencies that the Nium One program configures. For instance, if your client program is configured to support USD, GBP, and EUR currencies, then a given wallet can store balances in USD, GBP, and EUR.

A diagram showing wallet balances in three currencies.

Virtual account number

Nium has integrations with key banking partners to help you get and assign multiple virtual bank account numbers to meet your product needs. This helps you assign a VAN to collect locally or use the Society for Worldwide Interbank Financial Telecommunications (SWIFT) service. You can assign a USD local VAN, for example, so the account holder can collect or fund using a USD VAN with US Automated Clearing House (ACH) rails. Similarly, Nium can help you collect GBP using UK Faster Payment Service (FPS) rails by assigning a local GBP-enabled VAN.

Virtual and physical bank account

A physical bank account is held in the name of an account holder in the bank books. A virtual bank account is a feature that a bank offers to help an account holder get multiple account numbers linked to the primary physical bank account. It helps an account holder to receive money using multiple VANs and reconcile effectively. A virtual bank account isn't a separate account but it's a proxy account that's linked to the underlying primary physical bank account.

A diagram showing the Nium One program structure.

The diagram above captures the Nium structure. It shows a client with two client-level prefund accounts in the GBP and USD currencies. The client also has a certain number of account holders. Each account holder has a multicurrency wallet. The multicurrency wallet for account holder 'n' indicates the wallet has two currencies and each currenciy 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.