Key Concepts

Terminology

TermDescription
CustomerIndividual-Customers are the end-users holding the balance.
Corporate-Customers are the business entities holding the balance.
Multi-Currency WalletStorage mechanism for all currencies configured.
Virtual Account Numbers (VAN)Multiple account numbers all linked to a central account.
Wallet (Also called Account)Storage mechanism to keep balances in multiple currencies.

Platform Features

Nium One's platform is an open, flexible, comprehensive, and easy-to-embed fintech infrastructure platform. Companies use the Nium platform to launch and manage their fintech/payment programs that can use features such as:

  • Card issuing.
  • Domestic or Cross-border transfers.
  • Holding balances in multi-currency wallets.
  • Receiving multiple currencies into a single wallet locally; for example, receive GBP in the UK using FPS/CHAPS.

This guide will provide a quick overview of the platform feature.

3258

Typical NIUM Program Structure

Client and Product Configuration

It all starts with the setup of a platform client. As a part of the client setup, Nium will configure the product that meets your needs. The product configuration captures the multi-currency configurations, virtual account number-related configurations, card-issuing details, customer onboarding requirements, risks parameters, fee details, and so on. The following sections, provide a high-level overview of the various concepts involved in a typical program.

As the diagram above illustrates, the platform client is at the top of the hierarchy. As part of the platform client onboarding (that is as part of your onboarding before you could integrate and access the APIs), Nium will do the needful API configuration (IP whitelisting, Keys provisioning), and help you with details you need to connect to the platform API endpoints. You will use the APIs to onboard new customers, issue them cards, check balances, view transaction listings, manage payouts, and so on.

Depending on the nature of the product/program you are planning to build you might want to make use of the 'Prefund Accounts'. For instance, if what you are operating is a Corporate T&E, and funding to the underlying customer level wallet will only come from you, then you can fund first into your prefund account, and then allocate funds to the respective customer level wallets by using your prefund account as the funding source. You can fund into the prefund accounts using bank rails (local/SWIFT).

Customer

Next in the hierarchy is the Customer (Individual) or Customer (Corporate/Business). Individual-Customers are the end-users holding the balance. In a corporate T&E use case, this would be the staff member receiving the T&E card. In a consumer-funded use case, this would be the retail end-customer having the account. Depending on the nature of the product/program, the KYC and onboarding flow will differ. Work with your program representative in Nium. Where KYC is mandatory, Nium's e-KYC options (MyInfo in Singapore, greenID in Australia, Onfido in multiple markets) must be used to automate KYC and onboarding process.

The Customer (Corporate/Business) are relevant when your customer is a business entity (typical when your program is targeted to business-entities).

Wallet

Every Customer gets a wallet, which is governed by the product configuration that is set up for the Platform Client. The wallet will have placeholders or stores to carry just one or as many currencies as configured for the Platform Client.

You can consider Multi-Currency Wallet as the Multi-Currency Account assigned to the Customer. Terms Wallet and Account are used interchangeably. As mentioned before, the wallet acts as a store to keep balances in multiple currencies. Based on the product configuration, Nium Platform can automatically assign Virtual Account Numbers (VAN) at the wallet-currency level by using the configured VAN sources, or you can use Assign Payment ID API to assign Virtual Account Numbers at the currency level. For example, if the product configuration is such that a VAN for SGD from Nium's SG Bank Partner needs to be assigned, then when the wallet gets created the Platform will automatically allocate an SGD VAN from the SG Bank Partner and map that to the SGD currency of the Wallet. This would facilitate the account holder to top up SGD in the wallet by using the SG local bank rails (for instance - FAST in Singapore).

Nium can help with assigning VAN from the following countries:

  • SGD (local) in SG
  • GBP (local) in the UK
  • AUD (local) in AU
  • EUR (SEPA) in EU
  • USD (local) in the US
  • More...

📘

Info

Please consult your Nium contact to learn about additional VAN sources.

The multi-currency balances held within the wallet (if the product requires multi-currency support) can be exchanged between each other. Nium provides competitive FX rates and helps you with liquidity. The platform also permits moving funds from one customer’s wallet to another customer’s wallet - provided the transaction is performed in the same currency, and the two customers are under the same platform client.

Cards

As part of the client setup, you could work with Nium to configure one or many card programs. By using the Cards API endpoints, you could issue one or many cards (Plastic, Virtual - referring to the configured card programs) linked to a given Wallet. Note - the balance will always stay at the Wallet level, and cards are payment instruments to act on the balance.

📘

Info

Read about JIT Funding or Remote Host Authorization (RHA) model - for an alternative approach, where you can keep the Wallet level balances at your end.

Every time a card issued using the Nium Platform is used at the merchant or ATM terminal, Nium will process the card transactions (authorization, clearing, and settlement) and you do not need to worry about the transaction processing, reconciliation, and settlement. You can use the APIs to manage the cards (set limits, block/unblock cards), check balances at the wallet level, check transaction listing. You could subscribe to the webhooks to receive real-time events from Nium's Platform, and you could use that to manage communication with the end-users (push notifications, emails, SMS).

Payout

The final important feature is the payout. Nium has a competitive, vast remittance network built through global partnerships with banks and wallets. Using the funds available at the wallet level you can offer the domestic/cross-border payout service to your customers. A payroll product use case could enable the customer (the account holder holding his or her salary/wages in the wallet) to pay out cross-border. The platform seamlessly deducts funds from the wallet (the right currency balance) and transfers funds using Nium's global payment network. You can also make use of the FX conversion services to send from any of the available wallet currencies to any of the supported receive currency/corridors. For example, it would be possible to send from USD wallet-currency balance to PHP in the Philippines (bank-transfer).

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.

Example: 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 below diagram, the wallet has balances in three currencies.

Virtual Account Numbers (VAN)

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.

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.

The picture captures a high-level Nium One Program Structure. It has a Nium One 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.
  • 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 either one of the client prefund accounts.

Assigning VANs

As called out above, Nium One 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 numbers 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).

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.

On Demand

By using the “Assign Payment Id“ API function, you (Nium Client) can assign the Virtual Account Number from one of the configured VAN Sources (configured as part of the Nium 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.

Getting Details of Assigned VANs

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 related snippet 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, and 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 can collect funds into the USD/GBP account by using the SWIFT Code CHASSGSG and bank account number 20024397576.