Beneficiaries

A beneficiary is the individual or business authorized to receive funds from a specific source, such as a bank account or financial transfer.

In the context of Nium, a beneficiary represents the recipient of a payment or transfer. These details are essential to securely and accurately process transactions.

Beneficiary resource

The beneficiary resource represents the entity receiving funds in a payout. It includes essential details about the recipient, such as the entity's name, address, and email.

A beneficiary can either be a:

• Individual
• Business

Additionally, a beneficiary can be associated with one or more payment accounts. The following breaks down the fields and details for individual and business beneficiaries.

note

Required fields are marked with an asterisk (*).

Individual beneficiaries

Field	Description
beneficiaryName*	Full name of the beneficiary.
beneficiaryAccountType*	Account type: Individual or Corporate.
beneficiaryCountryCode*	ISO-2 country code of the beneficiary.
destinationCurrency*	3-letter ISO-4217 destination currency code.
payoutMethod*	Payout method: LOCAL, SWIFT, WALLET, CARD, or PROXY.
beneficiaryEmail	Email address of the beneficiary.
beneficiaryContactCountryCode	Mobile number country code (without +).
beneficiaryContactNumber	Mobile number digits only, without country code.
beneficiaryDob	Date of birth (format: YYYY-MM-DD). Applicable only to individual beneficiaries.
remitterBeneficiaryRelationship	The relationship between the sender and the receiving entity in the context of the transaction.

Business beneficiaries

Field	Description
beneficiaryName*	Full name of the beneficiary.
beneficiaryAccountType*	Account type: Individual or Corporate.
beneficiaryCountryCode*	ISO-2 country code of the beneficiary.
destinationCurrency*	3-letter ISO-4217 destination currency code.
payoutMethod*	Payout method: LOCAL, SWIFT, WALLET, CARD, or PROXY.
beneficiaryEmail	Email address of the beneficiary.
beneficiaryContactName	Contact person name (for corporate beneficiaries).
beneficiaryContactCountryCode	Mobile number country code (without +).
beneficiaryContactNumber	Mobile number digits only, without country code.
beneficiaryEntityType	Entity type of the business (e.g. partnership).
beneficiaryEstablishmentDate	Date of establishment (format: YYYY-MM-DD).
remitterBeneficiaryRelationship	The relationship between the sender and the receiving entity in the context of the transaction.

When you create a new beneficiary, a unique ID (beneficiaryHashId) is generated and assigned to the new beneficiary. Use this beneficiaryHashId and the beneficiary endpoint (or Nium Portal) to manage the beneficiary’s details and associated payment accounts.

Managing beneficiaries

Clients can manage beneficiaries using:

• The beneficiaries endpoint
• Nium Portal

Nium API

Use the beneficiary endpoint to manage beneficiaries.

Beneficiary requests

Request	Description
Add Beneficiary (V2)	Adds a new beneficiary and saves their information for future transactions.
Delete Beneficiary (V2)	Deletes a beneficiary and removes their information from the system.
Get Beneficiaries (V2)	Returns a list of beneficiaries linked to your account or organization.
Get Beneficiary Details (V2)	Fetches detailed information about a specific beneficiary using their unique ID.
Get Beneficiary Token (V2)	Retrieves an authentication token to securely interact with the beneficiary resource.
Update Beneficiary Details (V2)	Modifies an existing beneficiary’s details, such as contact information or payment accounts.

Nium Portal

Use the Beneficiaries page in Nium Portal to manage the different beneficiaries that have been created for a customer.

For additional details, see Nium Portal - Overview.

Creating a beneficiary

Use the Add Beneficiary (V2) request to add a beneficiary for a customer. The required details depend on the beneficiary type (entityType).

After creating a beneficiary, a unique beneficiaryHashId is assigned. Use this ID to manage the beneficiary.

When making the request, include:

• clientHashId – Your unique identifier, generated during onboarding.
• customerHashId – The unique identifier for the customer, generated when the customer is created.

Individual beneficiary

curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data-raw '{
  "beneficiaryName": "John Singh",
  "beneficiaryAccountType": "Individual",
  "beneficiaryCountryCode": "MY",
  "destinationCurrency": "PHP",
  "destinationCountry": "PH",
  "payoutMethod": "LOCAL",
  "beneficiaryAccountNumber": "NDIyOTk4MDA2OTk0ODY1MQ==",
  "beneficiaryAlias": "JohnSingh01",
  "beneficiaryBankName": "BDO Unibank",
  "beneficiaryEmail": "john@example.com",
  "beneficiaryAddress": "123 Tower Bridge",
  "beneficiaryCity": "Manila",
  "beneficiaryContactCountryCode": "60",
  "beneficiaryContactNumber": "9902892467",
  "routingCodeType1": "BANK CODE",
  "routingCodeValue1": "010269"
}'

Business beneficiary

curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data-raw '{
  "beneficiaryName": "Nium",
  "beneficiaryAccountType": "Corporate",
  "beneficiaryCountryCode": "MY",
  "destinationCurrency": "PHP",
  "destinationCountry": "PH",
  "payoutMethod": "LOCAL",
  "beneficiaryAccountNumber": "NDIyOTk4MDA2OTk0ODY1MQ==",
  "beneficiaryAlias": "Nium01",
  "beneficiaryBankName": "BDO Unibank",
  "beneficiaryEmail": "test@nium.com",
  "beneficiaryContactName": "Test",
  "beneficiaryContactCountryCode": "60",
  "beneficiaryContactNumber": "9902892467",
  "beneficiaryEntityType": "partnership",
  "beneficiaryEstablishmentDate": "2000-01-01",
  "remitterBeneficiaryRelationship": "partner",
  "routingCodeType1": "BANK CODE",
  "routingCodeValue1": "010269"
}'

Updating a beneficiary

The Update Beneficiary (V2) request enables you to update and modify the details of a beneficiary.

All properties of a beneficiary can be changed except:

• beneficiaryAccountType
• beneficiaryEmail
• beneficiaryEntityType

When updating a beneficiary, you must include:

• clientHashId
• customerHashId
• beneficiaryHashId

Deleting a beneficiary

Use the Delete Beneficiary (V2) request to delete a beneficiary.

For auditing reasons, the request will soft-delete the beneficiary. Deleting a beneficiary will also soft-delete all of the associated payment-accounts.

• Deleted beneficiaries won’t be listed in the GET or LIST beneficiary requests.
• To delete a beneficiary, you must include the:
  • clientHashId
  • customerHashId
  • beneficiaryHashId

Blocking a beneficiary

Use the Update Beneficiary (V2) request to block a beneficiary.

By default, beneficiaries have a status of active. Use the Update Beneficiary (V2) request to update the status of beneficiaries.

Blocking a beneficiary temporarily stops payments in case of an issue.

• To block a beneficiary, use the Update Beneficiary (V2) request and set the beneficiary.status to blocked.

Fetch beneficiary

The Fetch Beneficiary Details (V2) request allows you to retrieve details of a beneficiary.

By default, sensitive information is masked in the response. To retrieve unmasked data, set the unmaskData query parameter to true.

List beneficiaries

The List Beneficiaries (V2) request retrieves a list of beneficiaries for a customer.

• By default, sensitive information is masked in the response. To retrieve unmasked data, set the unmaskData query parameter to true.
• Items are sorted by creation-time.
• The response is paginated and uses cursor-based pagination.

Below is a sample response for a List Beneficiaries (V2) request.

[
  {
    "beneficiaryHashId": "1e3882af-c622-456e-8fbd-c951f3368577",
    "payoutHashId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "beneficiaryName": "Jeff Grell",
    "beneficiaryAccountType": "Individual",
    "beneficiaryCountryCode": "US",
    "beneficiaryEmail": "j*****@frontside.net",
    "destinationCountry": "US",
    "destinationCurrency": "USD",
    "payoutMethod": "LOCAL",
    "beneficiaryAccountNumber": "******5678",
    "routingCodeType1": "ACH CODE",
    "routingCodeValue1": "114916488"
  },
  {
    "beneficiaryHashId": "82bce9d9-f69a-45c7-ab6c-12167a64ed2f",
    "payoutHashId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "beneficiaryName": "Nium",
    "beneficiaryAccountType": "Individual",
    "beneficiaryCountryCode": "SG",
    "beneficiaryEmail": "t*****@nium.com",
    "beneficiaryContactCountryCode": "65",
    "beneficiaryContactNumber": "*******7890",
    "destinationCountry": "SG",
    "destinationCurrency": "SGD",
    "payoutMethod": "LOCAL",
    "beneficiaryAccountNumber": "******1234",
    "remitterBeneficiaryRelationship": "relationship",
    "beneficiaryDob": "2000-01-01"
  },
  // ... additional items ...
  {
    "beneficiaryHashId": "6fc33e40-f65b-4574-9b4d-3f2ba5491a6d",
    "payoutHashId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "beneficiaryName": "Nium",
    "beneficiaryAccountType": "Individual",
    "beneficiaryCountryCode": "MY",
    "beneficiaryEmail": "t*****@nium.com",
    "beneficiaryContactCountryCode": "60",
    "beneficiaryContactNumber": "*******7890",
    "destinationCountry": "MY",
    "destinationCurrency": "MYR",
    "payoutMethod": "LOCAL",
    "remitterBeneficiaryRelationship": "relationship",
    "beneficiaryDob": "2000-01-01"
  }
]

SCA Authentication for EU/UK clients

To comply with PSD2 regulations, EU/UK clients must include an authenticationCode in POST and PUT requests.

The authenticationCode is a one-time password (OTP) or verification code used as a second authentication factor before calling Nium APIs.