Spend and Payroll Management

Overview

In Spend Management and Payroll Management use cases, you need to onboard your corporate customer's employees under them. In other words, you need to establish a relationship between your corporate customer and their employees, also known as individual customers.

In Spend Management, your corporate customer funds the business expenses the employees make. For this purpose, the corporate customer issues cards on their accounts that employees can use. Your corporate customer's account funds the expenses. Those funds belong to your corporate customer and the employees 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/n1
  • 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 feature:

HTTP methodAPI nameAction
GETClient DetailsHelps you fetch the configuration details about a client.
POSTUnified Add CustomerHelps you onboard customers based on the client's configuration and preference. Links the individual customer to the corporate customer.
GETCustomer Details V2Helps you fetch a customer's details.
GETCustomer List V3Helps you fetch the customers for a client. Supports query parameters based on filtering to fetch details about a linked customer to a corporate customer.
POSTAdd Card V2Helps you issue a card for a customer.
GETCard ListHelps you return all the cards issued for a given wallet.
GETCard Details V2Helps you get details about a card.
GETTransactionsHelps you fetch the transaction details for a customer.
GETClient TransactionsHelps 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 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.

Unified Add Customer API parameterSpend ManagementPayroll ManagementOther use cases
Client configuration ChildMustHaveParent = True

BillingAddressAsCorporate = True
Client configuration ChildMustHaveParent = True

BillingAddressAsCorporate = False
Client configuration ChildMustHaveParent = True

BillingAddressAsCorporate = False
parentCustomerHashIdRequired

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.
kycModeRequired The acceptable value is MANUAL_KYC

Required

This field only accepts the following values:

  • E_KYC
  • MANUAL_KYC
  • SCREENING
  • E_DOC_VERIFY

Required

This field only accepts the following values:

  • E_KYC
  • MANUAL_KYC
  • SCREENING
  • E_DOC_VERIFY
billingAddress1OptionalRequiredRequired
billingAddress2OptionalRequiredRequired
billingCityOptionalRequiredRequired
billingCountryOptionalRequiredRequired
billingLandmarkOptionalRequiredRequired
billingStateOptionalRequiredRequired
billingZipCodeOptionalRequiredRequired

The following diagram shows the relationship between a corporate customer and an employee.

A diagram showing 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.

A diagram showing the assignment of a card to an employee linked to a corporate account.

A diagram showing the assignment of a card to an employee linked to a corporate account.

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.

A diagram showing the assignment of a card to an employee linked to their own account.

A diagram showing the assignment of a card to an employee linked to their own account.

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 segmentClient typeUse case
PayrollNon-financial platform clientsAs a payroll client, you want to onboard the employees under the corporate customer they belong to.
Spend ManagementNon-financial platform clientsAs 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.