Overview

▶ Run in Postman

Your customers or account holders get a wallet in multiple currencies. They use a wallet to make payments. 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.

Nium has integrations with key banking partners to help you obtain and assign virtual bank account numbers (VANs) to meet your product needs. This helps you assign VANs 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 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. A virtual bank account is a feature that a bank offers to help an account holder get multiple account numbers linked to a 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.

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 currency has its own VAN.

Nium supports assigning VANs at underlying multicurrency wallets and at client prefund accounts, as illustrated in the diagram. 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 image above, the client program is configured with a USD VAN and a GBP VAN, using the right USD VAN source and GBP VAN source. These configuration details about the VAN source are seen in the Client Details API response.

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

For brevity, only a section of the API response appears.

{
  ...
  "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 use JPMorgan Chase & Co. Singapore or JPM_SG as the bankName VAN source to issue GBP VAN and USD VAN. The specific bank account number assigned to the client's prefund account—for GPB: 20024397659 and for USD: 20024397659—is the 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 with you. This is 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 it along with account number 20024397659 to receive funds into either one of the client prefund accounts.

Nium One supports assigning VANs to the individual currency of the account holder’s multicurrency wallet or account. You see in the diagram 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.

VAN assignment

By using the Assign Payment ID API, you can assign the VAN from one of the configured VAN sources. These are configured as part of your client configuration. Before using this API, make sure to configure the list of VAN sources in your configuration. Nium does this configuration for you. To know the list of VAN sources configured in your configuration, use the Client Details API.

You can use the Virtual Account Details V2 API 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 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.

Multiple Wallets

Customers and account holders can use multiple wallets to hold their different balances and manage funds from any currency per their business needs.

A default wallet is always assigned to customers once they've been successfully onboarded/ After they're successfully onboarded, you can configure additional wallets for the customer. These additional wallets can hold balances in a single or multiple currencies, depending on the customer's business needs.

• Virtual accounts can also be assigned to any wallet for funding and collection purposes.
• Additionally, Payins and Payouts are available to support any wallet for better ledger management

Please note:

• Multiple Wallets is currently only supported for the following regions. We're actively working on bringing this feature to more regions.
  • United States (US)
  • United Kingdom (UK)
  • Canada (CA)
  • Singapore (SG)
  • Australia (AU)
  • Hong Kong (HK)

API Endpoints

Common Error Scenarios

The following is a breakdown of some common errors that can get returned when using the above requests: