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 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
communicationPreference	The preferred communication channel for the entity e.g. phone, email, etc.
contactNumber	A contact number for the entity.
dateOfBirth	The date of birth for an individual entity. Applicable only to individual beneficiaries.
email*	The email address of the entity.
entityType*	Specifies whether the entity is an individual or a business.
name*	The name of the entity.
nameLocal	The entity's name in their local language.
paymentAccounts	A list of payment account IDs associated with the beneficiary.
remitterBeneficiaryRelationship	The relationship between the sender and the receiving entity in the context of the transaction.

Business beneficiaries

Field	Description
businessRegistrationNumber*	A unique registration or identification number for a business entity.
businessType*	Type of a business. Applicable only to business beneficiaries with type corporate.
communicationPreference	The preferred communication channel for the entity e.g. phone, email, etc.
contactName	The contact person for a business entity.
contactNumber	A contact number for the entity.
email*	The email address of the entity.
entityType*	Specifies whether the entity is an individual or a business.
establishmentDate	The date the business entity was formed.
name*	The name of the entity.
nameLocal	The entity's name in their local language.
paymentAccounts	A list of payment account IDs associated with the beneficiary.
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.

Payment account

A payment-account represents the account details of a beneficiary. Specifically, a payment-account includes the banking details needed for beneficiaries to receive funds from payouts.

This includes details like the country, currency, payment method (LOCAL, SWIFT, PROXY, WALLET, and CARD), routing code, account number, etc.

The details needed to create a payment-account vary by payout corridor. The payout corridor is determined by:

• Country (payoutCountry)
• Currency (payoutCurrency)
• Payment method (payoutMethod)

The table below lists the most common required fields for setting up a beneficiary’s payment-account. For specific corridor or payment method requirements, see the Add Payment Account request.

Note: Required fields are marked with an asterisk (*).

Field	Description
alias	A custom name for the payment account to help you manage beneficiaries and their payment-accounts.
autoSweep	Details if the payment account has auto-sweep functionality enabled.
default	Details if the payment-account is the default account of the beneficiary.
owner	The details of the owner of the payment account, including name, address, and identifying details. Defaults to the beneficiary's information but can be overridden. For example, for a US beneficiary adding an IN, INR, local payment account, specify an Indian address using the owner.address property.
paymentMethod*	The method used for payments to the account. Available values include: LOCAL SWIFT PROXY WALLET CARD
payoutCountry*	The country code for the payment account where the beneficiary will receive funds. Equivalent to destinationCountry in earlier versions of the beneficiary endpoint.
payoutCurrency*	The currency code for the payment account where the beneficiary will receive funds. Equivalent to destinationCurrency in earlier versions of the beneficiary endpoint.
status	The current status of the payment account. Default is active. Available values include: active inactive closed fraudulent deleted
verificationStatus	The verification status of the payment account. Defaults to unverified. If Nium Verify is enabled, verification is performed asynchronously.

When you create a new payment-account, a unique ID (paymentAccountHashId) will be assigned to the newly created payment-account. Use the paymentAccountHashId to manage account details or issue a payout using the Transfer Money request.

Managing beneficiaries

Clients can manage beneficiaries using:

• The beneficiaries endpoint
• Nium Portal

Nium API

Use the beneficiary endpoint to manage beneficiaries and payment-accounts.

Beneficiary requests

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

Payment Account requests

Request	Description
Add Payment Account (V3)	Adds a new payment-account under an existing beneficiary.
Get Bank Details	Fetches details about the bank based on the submitted routing code.
Get Payment Account Details (V3)	Retrieves detailed information about a specific payment-account using its unique identifier.
Get Payments Accounts (V3)	Retrieves a list of all payment-accounts associated with a specific beneficiary.
Remove Payment Account (V3)	Deletes a payment-account from a beneficiary's list of accounts.
Update Payment Account Details (V3)	Updates the details of an existing payment-account, such as routing codes or account holder information.

Creating payment accounts

In addition to creating payment-accounts, use the Add Payment Account request to check the required details for a specific payout corridor.

Based on the payoutCountry, payoutCurrency, and payoutMethod used, the response to the request will detail the fields that are required to create a corridor specific payment-account for your beneficiary.

The data submitted in the request is validated against field-specific requirements, such as character limits, string length, and special characters.

This response helps simplify the process of creating beneficiaries and payment-accounts by eliminating the need to submit additional requests, like Fetch Supported Corridors or Beneficiary Validation Schema.

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

The following examples break down the steps to create a beneficiary and a payment-account.

Step 1: Add a beneficiary

Use the Add Beneficiary (V3) 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 and its associated payment-accounts.

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/v3/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 '{
  "authenticationCode": "123456",
    "entityType": "individual",
    "name": "John",
    "email": {
        "value": "test@nium.com"
    },
    "contactNumber": {
        "number": "+1234567890"
    },
    "communicationPreference": "email",
    "remitterBeneficiaryRelationship": "CFO",
    "dateOfBirth": "2000-01-01"
}'

Business beneficiary

curl --location 'https://gateway.nium.com/api/v3/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 '{
  "authenticationCode": "123456",
  "entityType": "corporate",
  "name": "Nium",
  "email": {
    "value": "test@nium.com"
  },
  "contactNumber": {
    "number": "+1234567890"
  },
  "communicationPreference": "email",
  "businessRegistrationNumber": "12345",
  "businessType": "partnership",
  "remitterBeneficiaryRelationship": "partner",
  "establishmentDate": "2000-01-01",
  "name_local": "名前",
  "contactName": "Test"
}'

Step 2: Add a payment account

Use the Add Payment Account (V3) request to add a payment-account for a beneficiary. Before adding a payment-account, you must first create a beneficiary.

The required details vary based on:

• Payout corridor – Determined by payout-country and payout-currency.
• Payment method – Defined by the payout-method used.

Be sure to include the following in your request:

• beneficiaryHashId
• clientHashId
• customerHashId

When you add a new payment-account, Nium checks for duplicates to prevent multiple entries of the same account.

The following payment-account properties are used to determine duplicates:

Payment Method	Properties
LOCAL or SWIFT	payoutCountry payoutCurrency paymentMethod beneficiaryHashId bankAccountNumber routingCodes
PROXY	payoutCountry payoutCurrency paymentMethod beneficiaryHashId proxyType proxyValue
WALLET	payoutCountry payoutCurrency paymentMethod beneficiaryHashId wallet.provider wallet
CARD	payoutCountry payoutCurrency paymentMethod beneficiaryHashId card details or token

Note: To add another payment-account for the same beneficiary, send the relevant request(s) multiple times.

Sample requests

The following example requests show how to create different types of payment-accounts.

US Local Payment Account

• payout-country: US
• payout-currency: USD
• payment-method: LOCAL

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
    "authenticationCode": "12345",
    "payoutCountry": "US",
    "payoutCurrency": "USD",
    "paymentMethod": "LOCAL",
    "alias": "test payment account",
    "accountType": "checking",
    "accountNumber": "0112345678",
    "owner": {
        "address": {
            "line1": "123 Elm St",
            "line2": "Suite 5",
            "city": "Anytown",
            "state": "Anystate",
            "countryCode": "us",
            "postalCode": "94536"
        },
        "identification": {
            "type": "type",
            "value": "value"
        }
    },
    "routingCodes": [
        {
        "type": "ach_code",
        "value": "114916488"
        }
    ]
}'

HK-GBP SWIFT Payment Account

• payout-country: HK
• payout-currency: GBP
• payment-method: SWIFT

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
  "authenticationCode": "12345",
  "payoutCountry": "hk",
  "payoutCurrency": "gbp",
  "paymentMethod": "swift",
  "alias": "test payment account",
  "default": true,
  "accountType": "checking",
  "bankCode": "402",
  "accountNumber": "0112345678",
  "owner": {
    "address": {
      "line1": "123 Elm St",
      "line2": "Suite 5",
      "city": "Anytown",
      "state": "Anystate",
      "countryCode": "us",
      "postalCode": "94536"
    },
    "identification": {
      "type": "type",
      "value": "value"
    }
  },
  "routingCodes": [
    {
      "type": "swift",
      "value": "ABCHHKHH"
    }
  ],
  "autoSweep": {
    "enable": true,
    "default": true
  }
}'

SG Proxy Payment Account

• payout-country: SG
• payout-currency: SGD
• payment-method: PROXY

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
  "authenticationCode": "12345",
  "payoutCountry": "sg",
  "payoutCurrency": "sgd",
  "paymentMethod": "proxy",
  "alias": "test payment account",
  "owner": {
    "address": {
      "line1": "123 Elm St",
      "line2": "Suite 5",
      "city": "Anytown",
      "state": "Anystate",
      "countryCode": "us",
      "postalCode": "94536"
    }
  },
  "proxy": {
    "type": "mobile",
    "value": "1234567891"
  }
}'

CN Wallet Payment Account

• payout-country: CN
• payout-currency: CNY
• payment-method: WALLET

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
  "authenticationCode": "12345",
  "payoutCountry": "cn",
  "payoutCurrency": "cny",
  "paymentMethod": "wallet",
  "alias": "test payment account",
  "owner": {
    "address": {
      "line1": "123 Elm St",
      "line2": "Suite 5",
      "city": "Anytown",
      "state": "Anystate",
      "countryCode": "us",
      "postalCode": "94536"
    },
    "identification": {
      "type": "type",
      "value": "value"
    }
  },
  "wallet": {
    "walletId": "123456789",
    "provider": "alipay"
  }
}'

CN Card Payment Account

• payout-country: CN
• payout-currency: CNY
• payment-method: CARD

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
  "authenticationCode": "12345",
  "payoutCountry": "cn",
  "payoutCurrency": "cny",
  "paymentMethod": "card",
  "alias": "test payment account",
  "owner": {
    "address": {
      "line1": "123 Elm St",
      "line2": "Suite 5",
      "city": "Anytown",
      "state": "Anystate",
      "countryCode": "us",
      "postalCode": "94536"
    },
    "name": "nium",
    "identification": {
      "type": "test",
      "value": "test"
    }
  },
  "card": {
    "issuerName": "nium",
    "number": "4111111111111111",
    "expiryDate": "2028-10"
  }
}'

CN Card-Token Payment Account

• payout-country: CN
• payout-currency: CNY
• payment-method: CARD with a card-token.

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
  "authenticationCode": "12345",
  "payoutCountry": "cn",
  "payoutCurrency": "cny",
  "paymentMethod": "card",
  "alias": "test payment account",
  "owner": {
    "address": {
      "line1": "123 Elm St",
      "line2": "Suite 5",
      "city": "Anytown",
      "state": "Anystate",
      "countryCode": "us",
      "postalCode": "94536"
    },
    "name": "nium",
    "identification": {
      "type": "test",
      "value": "test"
    }
  },
  "card": {
    "issuerName": "nium",
    "token": "<token-generated-using-card-widget-API>",
    "expiryDate": "2028-10"
  }
}'

Sample response

The following is a sample response for creating a payment-account with:

• payout-country: US
• payout-currency: USD
• payment-method: LOCAL

Sensitive information is masked in the response.

{
    "id": "16984a1f-df52-4808-948a-49b84967349e",
    "beneficiaryHashId": "91df5b80-2b48-47a0-b395-a941fca1e0da",
    "owner": {
        "name": "Nium",
        "address": {
            "line1": "*****",
            "line2": "*****",
            "city": "Anytown",
            "state": "*****",
            "countryCode": "us",
            "postalCode": "*****"
        },
        "identification": {
            "type": "type",
            "value": "*alue"
        }
    },
    "autoSweep": {
        "default": false,
        "enable": false
    },
    "alias": "test payment account",
    "payoutCountry": "US",
    "payoutCurrency": "USD",
    "paymentMethod": "LOCAL",
    "verificationStatus": {
        "status": "unverified"
    },
    "status": "active",
    "bankName": "Citizens State Bank of Luling",
    "accountType": "checking",
    "accountNumber": "******5678",
    "routingCodes": [
        {
            "type": "ach_code",
            "value": "114916488"
        }
    ],
    "openDate": "2024-12-11",
    "default": false
} of 

Updating a beneficiary

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

All properties of a beneficiary can be changed except:

• entityType
• email
• businessRegistrationNumber
• businessType

When updating a beneficiary, you must include:

• clientHashId
• customerHashId
• beneficiaryHashId

Updating a payment account

The Update Payment Account (V3) request works similarly to the Update Beneficiary (V3) request. It updates a beneficiary’s payment-account with the details provided in the request body.

All properties of a payment-account can be modified except:

• entityType
• email
• businessRegistrationNumber
• businessType

When updating a payment-account, you must include:

• beneficiaryHashId
• clientHashId
• customerHashId
• paymentAccountHashId

When you update a payment-account, the system checks for duplicates to prevent multiple entries of the same account. If the updated details match another payment-account assigned to the same beneficiary, the request is rejected.

The following payment-account properties are used to determine duplicates:

Payment Method	Properties
LOCAL or SWIFT	payoutCountry payoutCurrency paymentMethod beneficiaryHashId paymentAccountHashId bankAccountNumber routingCodes
PROXY	payoutCountry payoutCurrency paymentMethod beneficiaryHashId paymentAccountHashId proxyType proxyValue
WALLET	payoutCountry payoutCurrency paymentMethod beneficiaryHashId paymentAccountHashId wallet.provider wallet
CARD	payoutCountry payoutCurrency paymentMethod beneficiaryHashId paymentAccountHashId card details or token

Deleting a beneficiary

Use the Delete Beneficiary (V3) 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

Deleting a payment account

Use the Remove Payment Account (V3) to remove a payment-account from a beneficiary.

For auditing reasons, the request will soft delete the payment-account.

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

Blocking a beneficiary or payment account

Use the Update Beneficiary (V3) and Update Payment Account (V3) requests to block a beneficiary or payment-account.

By default, beneficiaries and payment-accounts have a status of active. Use the Update Beneficiary (V3) and Update Payment Account (V3) requests to update the status of beneficiaries and payment-accounts.

Blocking a beneficiary or payment-account temporarily stops payments in case of an issue.

• To block a beneficiary, use the Update Beneficiary (V3) request and set the beneficiary.status to blocked.
  • Note: Blocking a beneficiary also blocks all associated payment-accounts.
• To block a payment-account, use the Update Payment Account (V3) request and set the payment-account.status to inactive.

Fetch beneficiary or payment account

The Fetch Beneficiary Details (V3) and Fetch Payment Account Details (V3) requests allow you to retrieve details of a beneficiary or its associated payment-account.

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

Below is an example of a Fetch Payment Account Details (V3) response with masked data.

{
    "id": "16984a1f-df52-4808-948a-49b84967349e",
    "beneficiaryHashId": "91df5b80-2b48-47a0-b395-a941fca1e0da",
    "owner": {
        "name": "Nium",
        "address": {
            "line1": "*****",
            "line2": "*****",
            "city": "Anytown",
            "state": "*****",
            "countryCode": "us",
            "postalCode": "*****"
        },
        "identification": {
            "type": "type",
            "value": "*alue"
        }
    },
    "autoSweep": {
        "default": false,
        "enable": false
    },
    "alias": "test payment account",
    "payoutCountry": "US",
    "payoutCurrency": "USD",
    "paymentMethod": "LOCAL",
    "verificationStatus": {
        "status": "unverified"
    },
    "status": "active",
    "bankName": "Citizens State Bank of Luling",
    "accountType": "checking",
    "accountNumber": "******5678",
    "routingCodes": [
        {
            "type": "ach_code",
            "value": "114916488"
        }
    ],
    "openDate": "2024-12-11",
    "default": false
}

List beneficiaries or payment accounts

The List Beneficiaries (V3) and List Payment Accounts (V3) requests retrieve a list of beneficiaries for a customer and payment-accounts for a beneficiary.

• 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 and paymentAccountId.
• The response is paginated and uses cursor-based pagination.

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

{
    "beneficiaries": [
        {
            "id": "1e3882af-c622-456e-8fbd-c951f3368577",
            "customerHashId": "956ea8ad-e1d8-4dde-a0ac-a1efcebb8855",
            "name": "Jeff Grell",
            "entityType": "individual",
            "email": {
                "value": "j*****@frontside.net",
                "verified": false
            },
            "paymentAccounts": [],
            "status": "active"
        },
        {
            "id": "82bce9d9-f69a-45c7-ab6c-12167a64ed2f",
            "customerHashId": "956ea8ad-e1d8-4dde-a0ac-a1efcebb8855",
            "name": "Nium",
            "entityType": "individual",
            "email": {
                "value": "t*****@nium.com",
                "verified": false
            },
            "contactNumber": {
                "number": "*******7890",
                "verified": false
            },
            "paymentAccounts": [
                "91e35564-21a5-475c-ac19-25695cfa0cff",
                "d7af5ea5-a5c5-4bbe-bf9f-29d3bac85df6",
                "3f9986f5-94bb-4b8c-9cdb-fc4b31b176c7",
                "298d056d-ff85-4c1c-a316-f53b3120afde",
                "85038d2b-73fe-4568-96b6-aa91a041765f",
                "eeb3dcc7-a560-435e-9d80-db6be5656da3",
                "289874c5-3fed-498e-a6fc-465b60e0a8a2",
                "74fcdd1a-7cdc-4623-a704-8de2fe795438",
                "5d57a49e-698a-4825-89d8-bffbfc5ff302",
                "6ebf21cb-02d6-4c78-bad1-94fdc8b8d50d",
                "f7460e0b-a094-485f-b67a-1a7d733565a0",
                "9856660c-1e88-46f9-98a2-e833998a118f",
                "48355679-3c6c-4530-8a86-2decb90cb1ae",
                "46d318f8-09c2-4356-bd4f-822ed58fb2dc",
                "bfeb147b-167b-4d61-9ea2-ef7b34dd3f1d",
                "c31c942e-9023-4297-a9ec-78bb6856b98d",
                "7430ec23-78cf-4364-ad1b-7ef8bf78ae34",
                "9808d267-d179-4623-bd63-3f1f8356920e",
                "63294095-02f9-42bf-85a3-b1f988432f52",
                "e005a7d0-b1d9-4269-a80c-97934ffbc408",
                "0bea7568-5083-4b6a-9f9d-ecbbf7d01e4a",
                "2f9c1bb1-3c74-4ac6-b341-99368b52bef1",
                "a7210dfb-e9ac-48fa-a0cc-27e7a3a3a975",
                "1f1fe756-73de-4f8f-b7b8-8204a56b306d",
                "8f5eecf7-4b2f-4ee0-b7f9-0f38add1231d",
                "54d271a8-72b8-446e-8e9d-3bc77b57713a",
                "3bc54ac2-2dc2-4689-ad73-057f090020d8"
            ],
            "status": "active",
            "communicationPreference": "email",
            "remitterBeneficiaryRelationship": "relationship",
            "dateOfBirth": "2000-01-01"
        },
        .............
        .............,
        {
            "id": "6fc33e40-f65b-4574-9b4d-3f2ba5491a6d",
            "customerHashId": "956ea8ad-e1d8-4dde-a0ac-a1efcebb8855",
            "name": "Nium",
            "entityType": "individual",
            "email": {
                "value": "t*****@nium.com",
                "verified": false
            },
            "contactNumber": {
                "number": "*******7890",
                "verified": false
            },
            "paymentAccounts": [],
            "status": "active",
            "communicationPreference": "email",
            "remitterBeneficiaryRelationship": "relationship",
            "dateOfBirth": "2000-01-01"
        }
    ],
    "pagination": {
        "totalRecords": 67,
        "totalPages": 7,
        "currentCursor": "1e3882af-c622-456e-8fbd-c951f3368577",
        "nextCursor": "19d135ee-3286-49f5-9094-25e203dfa770"
    }
}

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.

Transfer money

With the changes in Beneficiary (V3) and Payment Account (V3), the Transfer Money request also accepts the paymentAccountHashId.

Below are examples of how to transfer money and create a payout using the paymentAccountHashId.

Step 1: Add a payment account

After creating a beneficiary, add a payment-account for them.

curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <client-api-key>' \
--data '{
    "authenticationCode": "12345",
    "payoutCountry": "US",
    "payoutCurrency": "USD",
    "paymentMethod": "LOCAL",
    "alias": "test payment account",
    "accountType": "checking",
    "accountNumber": "0112345678",
    "owner": {
        "address": {
            "line1": "123 Elm St",
            "line2": "Suite 5",
            "city": "Anytown",
            "state": "Anystate",
            "countryCode": "us",
            "postalCode": "94536"
        },
        "identification": {
            "type": "type",
            "value": "value"
        }
    },
    "routingCodes": [
        {
        "type": "ach_code",
        "value": "114916488"
        }
    ]
}'

Step 2: Transfer funds

Create a remittance to transfer funds using the paymentAccountHashId.

curl --location 'https://preprod.spend.nium.com/wallet-service/api/v1/client/20bd3def-49cb-45d6-ab2a-963640322b76/customer/d1218522-4f71-479b-a644-653275e389bf/wallet/aaaedd53-3e8d-4f98-a98e-47cb4f68a7ed/remittance' \
--header 'Content-Type: application/json' \
--header 'csrf_token: ....' \
--header 'Authorization: Bearer .....' \
--data '
{
    "purposeCode": "IR006",
    "customerComments": "Family Maintenance",
    "authenticationCode": "test",
    "beneficiary": {
        "paymentAccountId": "e6ee9f20-98c1-4779-814e-014636edd5d8"
    },
    "payout": {
        "source_amount": 1,
        "source_currency": "SGD"
    }
}'