Program, client, and client prefund account
Program
In the Nium One platform, a program is a logical grouping of clients based on their geographic region or company. Every program can have one or more logo IDs associated with it. Logo IDs specify a region and a bank identification number (BIN), or the first 6 digits on the card.
This is a fundamental construct in the platform and has to be mapped with a client at the time of the client creation in the system. Depending on the client use case, BIN, and region requirements, a new program can be defined. If it's not, the existing predefined program is mapped. The client gets access to one or more BIN ranges depending on the associated program.
Client
The client is an enterprise that wants to issue cards for their customers or employees. The client is directly associated with Nium. The customer is the actual cardholder who's onboarded under a particular client.
The client entity is created in the system at the time of the 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 out by the client as the first step of the client onboarding process.
The following configurations are managed at the client level.
Currencies
The platform supports multiple currencies for a customer wallet. These currencies need to be configured at the client level. Based on the client's requirements, these currencies are configured and available for each customer of the client.
There would be one base currency or account currency for the wallet. This base currency needs to be configured at the client level, too.
Virtual accounts
A virtual account is a unique reference to an actual Nium bank account generated to send and receive payments. It can be assigned to a client, or to the customers of the client, based on the use case. The client-level configuration for virtual accounts allows the virtual account number generation for clients and their customers.
Compliance configuration
The compliance configuration is specified by the Nium compliance team for clients based on their region, product type, and use case. This configuration is set at the client level and invoked whenever a new customer is onboarded. Based on the configuration, the Know Your Customer (KYC) process is performed.
APIs
Once the client is onboarded completely, and the client-level configuration is completed by the Nium team, then the client can fetch these details using the following API.
Client Details API
Use your clientHashId and x-api-key that the Nium team provides 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 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 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—according to 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 the 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 platform automatically verifies the transaction details and prefund request details. Based on that, it approves the prefund request and the funds are visible in the client prefund account.
The following are the client prefund related APIs:
3.1 Client Prefund Request API
This API allows platform clients to raise a prefund request in the system.
The client prefund request is 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 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 in the prefund balance using the Client Prefund Balances API.
Example request
curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/{{clientHashId}}/balances' \
-H 'x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j' \
-H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
-H 'x-client-name: client1'
You receive a response in the following format:
[
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "CLIENT_POOL",
"balance": 0,
"currency": "THB",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "CLIENT_POOL",
"balance": 0,
"currency": "GBP",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-08-06 04:08:01",
"accountType": "CLIENT_POOL",
"balance": 4931.185,
"currency": "SGD",
"isDefault": "true"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-08-06 04:15:01",
"accountType": "CLIENT_POOL",
"balance": 4981.332,
"currency": "USD",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "CLIENT_POOL",
"balance": 0,
"currency": "MYR",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-08-06 04:15:01",
"accountType": "WALLET_POOL",
"balance": 65,
"currency": "USD",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "WALLET_POOL",
"balance": 0,
"currency": "MYR",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "WALLET_POOL",
"balance": 0,
"currency": "THB",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-07-14 05:16:09",
"accountType": "WALLET_POOL",
"balance": 0,
"currency": "GBP",
"isDefault": "false"
},
{
"createdAt": "2020-07-14 05:16:09",
"updatedAt": "2020-08-06 04:08:52",
"accountType": "WALLET_POOL",
"balance": 5,
"currency": "SGD",
"isDefault": "true"
}
]
Updated about 1 year ago