Client, Program, Client Prefund Accounts

Program

In the NIUM platform, a program is a logical grouping of clients based on their region or company. Every program can have one or more logo ids associated with it. Logo ids specify the region and the BIN (bank identification number or the first 6 digits on the card) range.

This is a fundamental construct in the platform and has to be mapped with a client at the time of client creation in the system. Depending on the client use-case, BIN and region requirements, a new program can be defined, or else the existing pre-defined program will be mapped. The client gets access to one or more BIN ranges depending on the associated program.

Client

The clients are enterprises that want to issue cards for their customers (or employees) and are directly associated with NIUM whereas the customers are the actual cardholders who are onboarded under the particular client.

The Client entity is created in the system at the time of client onboarding to manage multiple client-level parameters under this entity. These client-level details are entered into the system based on the Program Application Form filled by the client as the first step of client onboarding.

The following configurations are managed at the client level.

Currencies

The NIUM platform supports multiple currencies for customer wallets. Each wallet can have multiple currencies associated with it. These currencies need to be configured at the client level. Based on the client requirements, these currencies are configured and all the configured currencies would be available for each customer of that client.

There would be one base currency (or account currency) for the wallets. This base currency has to be configured at the client level too.

Virtual Accounts

A virtual account is a unique reference to an actual NIUM bank account generated for the ease of sending and receiving payments. It can be assigned to a client or to the customers of the client based on use-case. The client-level configuration for virtual accounts enables virtual account number generation for clients as well as their customers.

Fees

The NIUM platform charges some account and transaction-specific fees. Once the fees structure is mutually accepted between NIUM and clients, then these are configured in the platform at the client level. Following are the types of fees and their definitions.

Fee	Description
ACCOUNT_OPENING_FEE	One-time account opening fee charged on customer creation.
ACCOUNT_MAINTENANCE_FEE	Monthly fee charged for account maintenance.
ACCOUNT_INACTIVE_FEE	Monthly fee charged for inactive accounts.
PLASTIC_FEE	One-time physical card issuance fee.
REPLACEMENT_FEE	One-time physical card replacement fee.
VIR_CARD_FEE	One-time virtual card issuance fee.
ADDON_CARD_FEE	Per transaction fee charged for each ADD_ON card issuance.
TRANSACTION_MARKUP	Markup charged by NIUM on each transaction.
ATM_FEE	Per transaction fee charged on an ATM transaction.
INTERNATIONAL_ATM_FEE	Per transaction fee charged on an international ATM usage.
ATM_DECLINE_FEE	Per transaction fee charged on an ATM transaction decline.
NON_ATM_DECLINE_FEE	Per transaction fee charged on a non-ATM transaction decline (MCC is NOT EQUAL TO 6011)
ECOM_FEE	Per transaction fee charged on e-commerce/online transactions.
POS_FEE	Per transaction fee charged on a POS transaction.
WALLET_REFUND_FEE	Per transaction fee charged on wallet refund.
REMIT_BANK_FEE	Per transaction fee charged on Remittance_Debit transaction when the payout type is LOCAL or SWIFT.
REMIT_WALLET_FEE	Per transaction fee charged on Remittance_Debit transaction when the payout type is WALLET.
REMIT_PROXY_FEE	Per transaction fee charged on Remittance_Debit transaction when the payout type is PROXY.

Limits

The NIUM platform supports advanced spend control features in the form of limits and restrictions. There are multiple types of limits out of which some can be set up at the client level and some can be set up at card level.

The client level limits are divided into two categories; Regulatory Limits and Auth Limits. The client level limits are applicable for all the customers, wallets, and cards created under that client. The regulatory limits are account-specific limits(balance amount and count etc) while the auth limits are transaction-specific limits.

The NIUM platform provides the limit configurations based on the compliance clearance level of customers. For example, the customer is created but the KYC process is not completed, then the customer can make transactions till a certain limit only whereas if the KYC is completed, then the limits would be higher and different.

The restrictions can be set up at the card level only in which we can specify the types of merchant categories where cards should be allowed.

Compliance Configuration

The compliance configurations are specified by the NIUM compliance team for clients based on their region, product type, and use case. These configurations are set at the client level and invoked whenever the new customer is onboarded. Based on the configurations, the KYC process would be performed.

APIs

Once the client is onboarded completely and these client-level configurations are completed by the Nium team, then the client would be able to fetch these details using following APIs.

Client Details API

Note: Please use your clientHashId and x-api-key (that Nium team will provide you)

Example Request:

curl -X GET 'https://apisandbox.spend.nium.com/api/v1/client/{{clientHashId}}' \
  -H 'x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j' \
    -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
      -H 'x-client-name: client1'

You will receive the response in the following format

{
  "name": "Acme Inc",
  "email": "[email protected]",
  "contactNo": "+6588008100",
  "markup": 0.5,
  "clientHashId": "82c68bab-3c04-3451-8d7b-cb38ad713d97",
  "logoUrl": null,
  "countryCode": "SG",
  "clientIdNumber": "",
  "notificationWebhook": "https://acme-notification.com/webhook",
  "complianceStatusCallbackUrl": "https://acme-notification.com/callback/compliance?customerHashId=%s",
  "multiCurrencySupported": false,
  "deduplicationFlag": false,
  "customerAuthUrl": null,
  "prefundName": "Acme Inc",
  "fundingInstrumentType": "RESTRICTED",
  "cardTxnRedirectUrl": null,
  "applePaySupport": false,
  "googlePaySupport": false,
  "samsungPaySupport": false,
  "paymentIds": [
    {
      "currencyCode": "SGD",
      "uniquePayerId": null,
      "uniquePaymentId": "8850932057194",
      "bankName": "DBS_SG"
    },
    {
      "currencyCode": "HKD",
      "uniquePayerId": null,
      "uniquePaymentId": "7770215",
      "bankName": "DBS_HK"
    },
    {
      "currencyCode": "SGD",
      "uniquePayerId": null,
      "uniquePaymentId": "20024394487",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "HKD",
      "uniquePayerId": null,
      "uniquePaymentId": "20024394487",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "AUD",
      "uniquePayerId": null,
      "uniquePaymentId": "20024394487",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "USD",
      "uniquePayerId": null,
      "uniquePaymentId": "20024394487",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "EUR",
      "uniquePayerId": null,
      "uniquePaymentId": "20024394487",
      "bankName": "JPM_SG"
    },
    {
      "currencyCode": "HKD",
      "uniquePayerId": null,
      "uniquePaymentId": "800205697",
      "bankName": "JPM_AU"
    },
    {
      "currencyCode": "AUD",
      "uniquePayerId": null,
      "uniquePaymentId": "800205697",
      "bankName": "JPM_AU"
    },
    {
      "currencyCode": "USD",
      "uniquePayerId": null,
      "uniquePaymentId": "800205697",
      "bankName": "JPM_AU"
    },
    {
      "currencyCode": "EUR",
      "uniquePayerId": null,
      "uniquePaymentId": "800205697",
      "bankName": "JPM_AU"
    }
  ],
  "whitelistedRemitterAccounts": [],
  "allowThirdPartyFunding": false,
  "cardTxnProductCode": null,
  "cardTxnNarrative": null,
  "complianceCallbackUrl": null,
  "currencyAuthorizationType": "MULTI",
  "minimumCustomerAge": 18,
  "currencies": [
    {
      "currencyCode": "SGD",
      "decimalUnit": 2,
      "settlementCurrencyType": "BILLING_CURRENCY",
      "remittanceAllowed": false,
      "authorizationOrder": 0
    },
    {
      "currencyCode": "AUD",
      "decimalUnit": 2,
      "settlementCurrencyType": "BILLING_CURRENCY",
      "remittanceAllowed": false,
      "authorizationOrder": 1
    },
    {
      "currencyCode": "HKD",
      "decimalUnit": 2,
      "settlementCurrencyType": "BILLING_CURRENCY",
      "remittanceAllowed": false,
      "authorizationOrder": 2
    },
    {
      "currencyCode": "USD",
      "decimalUnit": 2,
      "settlementCurrencyType": "BILLING_CURRENCY",
      "remittanceAllowed": false,
      "authorizationOrder": 3
    },
    {
      "currencyCode": "EUR",
      "decimalUnit": 2,
      "settlementCurrencyType": "BILLING_CURRENCY",
      "remittanceAllowed": false,
      "authorizationOrder": 4
    }
  ],
  "accountValidation": false,
  "regulatoryRegion": "SG",
  "licenseEntity": "THIRD_PARTY",
  "ekycRedirectUrl": "https://acme-notification.com/callback/redirect?customerHashId=%s"
}

Client Prefund

The client prefund process means adding balance to the client account on the Nium platform. This balance can then be used to fund the wallets of customers. The client prefund process involves the following steps.

1. Bank Transfer

You need to transfer money to Nium's bank account (virtual account number) as per the account details provided to the client. After the money transfer, you need to note the Transfer Reference Number.

2. Initiate Prefund Request

You can do this through Client Prefund Request API. You need to provide all required details, which may include amount, reference number, date of transfer, currency, Nium account number, client account number, and attachments.

3. Reconciliation

The Nium platform automatically verifies the transaction details and prefund request details and based on that, it will approve the prefund request and the funds will be visible in the client prefund account.

The client prefund related APIs are as given below.

3.1 Client Prefund Request API

This API allows our clients to raise a prefund request in the system.

The client prefund request should be initiated after the fund transfer to the provided virtual account number.

Example Request

curl -X POST \
  https://apisandbox.spend.nium.com/api/v1/client/{{clientHashId}}/prefund \
    -H 'content-type: application/json' \
    -H 'x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j' \
    -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
    -H 'x-client-name: client1' \
    -d '{
  "bankReferenceNumber": "712347512376",
  "clientAccountNumber": "615234671328",
  "comments": "Client Prefund",
  "currencyCode": "SGD",
  "dateOfTransfer": "2019-11-24",
  "niumAccountNumber": "133876812367",
  "amount": 1000,
  "requesterId": "8123768123"
}'

You will receive a response in the following format.

{
  "message": "Prefund request added successfully.",
  "status": "Pending",
  "amount": 1000,
  "systemReferenceNumber": "CP8790469553",
  "uniquePayerId": null,
  "uniquePaymentId": null
}

3.2 Client Prefund Balances API

Once the prefund request is approved, you can fetch the information available prefund balance using Client Prefund Balances API.