Update beneficiary

put

https://api-beneficiary-beta.vertofx.com/recipients/{recipientId}

Update an existing beneficiary by ID while preserving omitted fields and validating the record against its currency, payment mode, and beneficiary type.

Path Params

recipientId

string

required

id of the account

Body Params

Update payload for an existing beneficiary. The update is merged with the existing record, so most body fields are optional. When a field is supplied, the same format/pattern/enum constraints as addBeneficiaryClient apply.

currencyId, paymentMode and beneficiaryType must always be supplied so downstream validation can resolve the correct currency/payment-mode configuration.

Runtime conditional rules (enforced by the service, not by the JSON schema):

Non-stablecoin paymentModes (LOCAL, INTERNATIONAL, MOBILE_MONEY, HK_BANK): accountNumber, bankCode, bankName and bankAddress.countryCode are required.
INTERNATIONAL paymentMode additionally requires beneficiaryAddress.addressLine1 and beneficiaryAddress.countryCode.
When beneficiaryType is company, companyName is required (non-stablecoin). When individual, firstName and lastName are required. myOrganisation has no name field requirement.
Stablecoin paymentMode (STABLECOIN): cryptoCurrencyWalletAddress, blockchain, cryptoCurrency and cryptoCurrencyWalletHostedOption are required. When accountLabel (wallet nickname) is supplied, companyName is required; otherwise either companyName or both firstName+lastName must be provided, together with a full beneficiaryAddress (addressLine1, city, countryCode, postCode, stateOrProvience).
SWIFT bank codes whose country (chars 5-6) is in the sanctioned (OORA) list are rejected.
When the client's company category is financial services or crypto, nestedType is required.
Per-currency paymentMode restrictions: KES/TZS → LOCAL|INTERNATIONAL|MOBILE_MONEY; KRW → LOCAL; XAF → LOCAL|MOBILE_MONEY.

userRecordId

integer | null

accountNumber

string | null

Trimmed before validation. For IBAN-based modes, spaces and hyphens are accepted and stripped, then the value is uppercased before validation. Required for non-stablecoin payment modes. Character set is intentionally permissive at the schema level; exact per-currency/payment-mode format (e.g. TZS/KES/XAF MOBILE_MONEY expect +<country>-XXXXXXXXX) is enforced by the runtime validator.

accountLabel

string | null

Wallet nickname (primarily for stablecoin). Allowed characters: alphanumeric, spaces, and .,'&@#$^*/!()

cryptoCurrency

string | null

enum

Required when paymentMode is stablecoin.

Allowed:

blockchain

string | null

enum

Required when paymentMode is stablecoin.

Allowed:

cryptoCurrencyWalletAddress

string | null

Required when paymentMode is stablecoin. Must be a valid 0x-prefixed 40-character hex address.

cryptoCurrencyWalletHostedOption

string | null

enum

Required when paymentMode is stablecoin.

Allowed:

cryptoCurrencyWalletHostedOn

string | null

enum

This field is based on the selected cryptoCurrencyWalletHostedOptions, i.e. store custodian/exchange/self-hosted wallet details. This is null if cryptoCurrencyWalletHostedOptions is not_sure

cryptoCurrencyWalletHostedOnOtherOption

string | null

fundType

string | null

country

string | null

bankAddress

object

When supplied, countryCode must reference an active supported 2-letter country code.

bankCode

string | null

Trimmed before validation. Required for non-stablecoin payment modes. SWIFT codes belonging to sanctioned (OORA) countries are rejected.

altNationalId

string | null

Optional alternate national identifier. Trimmed before validation.

bankName

string | null

Required for non-stablecoin payment modes.

companyName

string | null

Required when beneficiaryType is 'company' (non-stablecoin). Base validation allows alphanumerics and spaces; some currencies (e.g. AUD/CAD/CNY/HKD/IDR/JPY and other Asian locales) additionally permit . and - in company names — enforced by the runtime validator.

firstName

string | null

Required when beneficiaryType is 'individual' (non-stablecoin). Only alphanumeric characters and spaces are allowed.

lastName

string | null

Required when beneficiaryType is 'individual' (non-stablecoin). Only alphanumeric characters and spaces are allowed.

beneficiaryAddress

object

Required for international payment mode and for currencies/payment modes where the configured rules mark beneficiary address as required. All individual fields (when present) must be up to 35 characters; only alphanumeric characters, spaces, and commas are allowed.

beneficiaryType

string

enum

required

Type of beneficiary.

Allowed:

isRFIAccountUpdation

boolean | null

companyEstablishmentDate

string | null

companyCountryOfTax

string | null

companyIncorporationNumber

string | null

currencyId

integer

required

forFurtherCredit

object

partyType

string | null

enum

Allowed:

paymentMode

string

enum

required

Payment method. Accepted values depend on the currency:

KES, TZS: LOCAL, INTERNATIONAL, MOBILE_MONEY
KRW: LOCAL
XAF: LOCAL, MOBILE_MONEY
All other supported currencies: LOCAL, INTERNATIONAL, STABLECOIN, HK_BANK

Allowed:

paymentCapabilities

object | null

isUpdateRequired

boolean | null

updateReason

string | null

companyId

integer | null

incoming_capability

string | null

customReferenceLabel

string | null

isSelfAccount

boolean | null

isDefault

boolean | null

nestedType

object

Required when the authenticated client company is categorised as 'financial services' or 'crypto' (nested client).

documentDetails

array of objects | null

documentDetails

copVerification

string | null

nativeCompanyName

string | null

branchCode

string | null

companyRegistrationNumber

string | null

mobileNumber

string | null

accountType

string | null

Response

200Successfully updated beneficiary