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 to true, you're required to link the individual customer or employee, to your corporate customer. If the flag is set to false, 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 to true.
  • For Payroll Management clients, you need to configure the billingAddressAsCorporate flag to false.

🗒️

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 endpoints

The following APIs support the Spend and Payroll Management use cases:

Configure the corporate customer and 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 API.

The following table gives information about the above API parameters which are needed to connect the individual customer to the corporate customer.

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 linked to a corporate account

To add a card for your corporate customers' employees or individual customers, who are linked to the corporate wallet, follow these steps:

1. Issue a card in your corporate customer's account using the Add Card V2 API.
2. In the Add Card V2 API include the following information:
   1. customerHashId: This parameter is required. This field accepts the value as the customerHashId of your corporate customer.
   2. walletHashId: This parameter is required. This field accepts the value as the walletHashId of your corporate customer.
   3. childCustomerHashId: This parameter is optional. This field accepts the value as customerHashId of the individual customer, or employee, who uses the card.
      1. The customerHashId, included in the childCustomerHashId field, needs to belong to the individual customer linked to the corporate customer.
      2. The corporate customer, whose wallet is used, and the individual customer should be from the same client setup.
      3. Make sure your individual customer and the corporate customer associated with the given corporate customer wallet, have their KYC status clear.

🗒️

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 B
• customerHashId: customerHashId of the corporate customer A
• walletHashId: 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.

Assign a card to an employee linked to their account

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