Parent-child hierarchy
Overview
A parent-child structure means one data item is the parent of another data item, the child. In a parent-child hierarchy, a relationship is established between the corporate customer—the parent—and the individual customer—the child. This relationship is useful in Spend Management and Payroll use cases.
In Spend Management and Payroll Management use cases, you need to onboard your parent corporate customer's child, or individual employee, under them.
In Spend Management, your corporate customer funds the business expenses the employee makes. The corporate customer issues a card on their accounts that the employee can use. Your corporate customer's account funds the expenses. The funds belong to your corporate customer and the employee can only use the money for business purposes.
In Payroll Management, your corporate customer credits salaries to their employees from their corporate customer account and into their individual accounts. Those funds belong to the employees, and they can use them as needed. The cards issued to the individual accounts use their own funds for personal expenses.
Prerequisites
- If the flag
childMustHaveParent
is set totrue
, you're required to link the individual customer or employee, to your corporate customer. If the flag is set tofalse
, you can choose to either link or not link the individual customer to your corporate customer. - The flag
billingAddressAsCorporate
lets the individual customer and the corporate customer have the same billing address.- For Spend Management clients, you need to configure the
billingAddressAsCorporate
flag totrue
. - For Payroll Management clients, you need to configure the
billingAddressAsCorporate
flag tofalse
.
- For Spend Management clients, you need to configure the
NOTE
If the corporate customer's billing address changes, the platform automatically updates the individual customer's billing address to be the same. You need to onboard your corporate customer before you onboard their individual employees or customers.
API server URLs
Use the following host names to distinguish the API calls between the different working environments.
- Sandbox:
https://gateway.nium.com
- Production:
https://api.spend.nium.com
Supported countries and currencies
To see all the countries and currencies that the Spend and Payroll Management capabilities support, refer to The Nium Playbook
API requests
The following APIs support the Spend and Payroll Management use cases:
HTTP method | API name | Action |
---|---|---|
GET | Client Details | Helps you fetch the configuration details about a client. |
POST | Unified Add Customer | Helps you onboard customers based on the client's configuration and preference. Links the individual customer to the corporate customer. |
GET | Customer Details V2 | Helps you fetch a customer's details. |
GET | Customer List V3 | Helps you fetch the customers for a client. Supports query parameters based on filtering to fetch details about a linked customer to a corporate customer. |
POST | Add Card V2 | Helps you issue a card for a customer. |
GET | Card List | Helps you return all the cards issued for a given wallet. |
GET | Card Details V2 | Helps you get details about a card. |
GET | Transactions | Helps you fetch the transaction details for a customer. |
GET | Client Transactions | Helps you fetch the transaction details at the client level. It also supports query parameters based on filtering to fetch details of the transactions for the customer. |
Configure employee relationship
To establish the connection between your corporate customer and an individual customer or employee, onboard the corporate customer first and then onboard the employee using the Unified Add Customer request.
The following table gives information about the above API parameters which are needed to connect the individual customer to the corporate customer.
Unified Add Customer API parameter | Spend Management | Payroll Management | Other use cases |
---|---|---|---|
Client configuration ChildMustHaveParent = True BillingAddressAsCorporate = True | Client configuration ChildMustHaveParent = True BillingAddressAsCorporate = False | Client configuration ChildMustHaveParent = True BillingAddressAsCorporate = False | |
kycMode | Required The acceptable value is: MANUAL_KYC | Required This field only accepts the following values:
| Required This field only accepts the following values:
|
parentCustomerHashId | Required The acceptable value is corporate customerHashId to which the employee is linked.The corporate customer's Know Your Customer (KYC) status needs to be clear. The corporate customer and the individual customer should be from the same client setup. | Required The acceptable value is corporate customerHashId to which the employee is linked.The corporate customer's KYC status needs to be clear. The corporate customer and the individual customer should be from the same client setup | Optional The acceptable value is corporate customerHashId to which the individual customer is linked. |
firstName | Required Accepts the first name of the customer. Maximum character limit: 40 | Optional | Optional |
lastName | Required This field accepts the last name of the customer. Maximum character limit: 40 | Optional | Optional |
identificationDoc | Required An object that accepts the customer's identification document. The maximum allowed size of this payload is 10 MB. A separate object is needed for each document image. Required fields: identificationDoc#identificationType identificationDoc#identificationDocument | Optional | Optional |
mobile | Required Accepts the mobile number of the customer--number only--without the country code. Maximum character limit: 20 | Optional | Optional |
email | Required Accepts the unique email address of the customer. Maximum character limit: 60 | Optional | Optional |
billingAddress1 | Optional | Required | Required |
billingAddress2 | Optional | Required | Required |
billingCity | Optional | Required | Required |
billingCountry | Optional | Required | Required |
billingLandmark | Optional | Required | Required |
billingState | Optional | Required | Required |
billingZipCode | Optional | Required | Required |
The following diagram shows the relationship between a corporate customer and an employee.
You can fetch the customer details using the Customer Details V2 API. You can find the corporate customer's parentCustomerHashId
in the customer details.
IMPORTANT
Once an individual customer is created, with the
parentCustomerHashId
parameter, you won't be able to update that property. If you need to update that property, you need to block the previous individual customer and create a new one to link them to another corporate customer.
You can also fetch a customer list using the Customer List V3 API. This endpoint shows the parentCustomerHashId
parameter for all individual customers. You can fetch all the individual customers linked to a corporate customer by providing the parentCustomerHashId
as a part of the query parameter.
Add a card to an employee
To add a card for your corporate customers' employees or individual customers, who are linked to the corporate wallet, follow these steps:
- Issue a card in your corporate customer's account using the Add Card V2 API.
- In the Add Card V2 API include the following information:
customerHashId
: This parameter is required. This field accepts the value as thecustomerHashId
of your corporate customer.walletHashId
: This parameter is required. This field accepts the value as thewalletHashId
of your corporate customer.childCustomerHashId
: This parameter is optional. This field accepts the value ascustomerHashId
of the individual customer, or employee, who uses the card.- The
customerHashId
, included in thechildCustomerHashId
field, needs to belong to the individual customer linked to the corporate customer. - The corporate customer, whose wallet is used, and the individual customer should be from the same client setup.
- Make sure your individual customer and the corporate customer associated with the given corporate customer wallet, have their KYC status clear.
- The
NOTE
The corporate customer is the owner of the card, and the employee is the user of the card.
Fetch the childCustomerHashId
with the Card Details V2 API. The childCustomerHashId
is visible in the details section of the API.
To fetch the details for Card B, in the above diagram, provide the values for the following parameters:
cardHashId
:cardHashId
of Card BcustomerHashId
:customerHashId
of the corporate customer AwalletHashId
:walletHashId
of the corporate customer
All path parameters are required to fetch any of the card details.
You can retrieve the card list using the Card List API, which contains the childCustomerHashId
field. This operation lets you fetch all the cards listed that are linked to a corporate customer by providing the customerHashId
in the path parameter. The query parameter includes the childCustomerHashId
.
Assigning a card to an employee
This use case applies to Payroll Management where the funds belong to the employees, and they can spend the funds for their own purposes. For such a scenario, you can establish the relationship between a corporate customer and its employees, and the cards are assigned to an employee linked to their own account.
In this event, the childCustomerHashId
is null
and the customerhashId
and the walletHashId
are of the individual customer.
Transaction management
You can fetch transactions at the client and wallet level via the Client Transactions API and the Transactions API, respectively. The transaction details include the childCustomerHashId
parameter, which provides the customerHashId
of the individual customer, or employee, who made the transaction.
You can also retrieve all employee transactions by providing the childCustomerHashId
parameter in the query of the Client Transactions API and the Transactions API. You need to include the customerHashId
of the individual customer or employee, in the childCustomerHashId
field and include it as a query parameter in the API. The response provides all the transactions the employee makes.
Use cases
Target segment | Client type | Use case |
---|---|---|
Payroll | Non-financial platform clients | As a payroll client, you want to onboard the employees under the corporate customer they belong to. |
Spend Management | Non-financial platform clients | As a spend management client, you want to onboard the employees under the corporate customer they belong to. You want to fund the expenses made by the employees from the corporate customer’s account. |
Updated 17 days ago