API Reference
FAQSandbox Portal

Update an existing beneficiary

put
https://api-beneficiary-sandbox.vertofx.com/recipients/

Update an existing beneficiary account. Fields are merged with the existing record; currencyId, paymentMode and beneficiaryType must always be supplied so downstream validation can resolve the correct currency/payment-mode configuration.

📘

Check your base URL

Each Verto service has its own host. Use the base URL shown in the endpoint definition on this page — do not reuse a host from another service.

Sandbox hosts end in -sandbox.vertofx.com; the matching production host replaces sandbox with beta. Sending a request to the wrong environment returns 403.

See URLs (Sandbox vs Production) for the full service-by-service list.


Path Params
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.

string | null
^[0-9a-zA-Z\s\-+./'"]*$

Trimmed before validation, then uppercased for IBAN. Required for non-stablecoin payment modes. Allowed characters at schema level: alphanumeric and -+./'". Exact per-currency/payment-mode format (e.g. TZS/KES MOBILE_MONEY expect +<country>-XXXXXXXXX) is enforced by the runtime validator.

string | null

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

string | null
enum

Required when paymentMode is stablecoin.

Allowed:
string | null
enum

Required when paymentMode is stablecoin.

Allowed:
string | null

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

string | null
enum

Required when paymentMode is stablecoin.

Allowed:
string | null
enum

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

string | null
string | null
bankAddress
object

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

string | null

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

string | null

Optional. A secondary identifier for the beneficiary account where accountNumber/bankCode alone isn't enough — for example a mobile money provider (M-PESA) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency. Trimmed before validation.

string | null
^.+$

Required for non-stablecoin payment modes.

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.

string | null

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

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.

string
enum
required

Type of beneficiary.

Allowed:
string | null
string | null
string | null
integer
required

Currency id for this beneficiary. Obtain currencyId from the guide on Currency Codes Mapping.

string
enum
required

How the payout is delivered. Choose based on the rail:

  • LOCAL — Domestic bank transfer in the beneficiary's market.
    Use a normal bank account number plus the local bank identifier
    (sort code, local bank code, or SWIFT/BIC as required for the currency).
    Example: GBP Faster Payments (bankCode = sort code, accountNumber = 8-digit account).

  • INTERNATIONAL — Cross-border bank transfer via SWIFT rails.
    Requires beneficiaryAddress.addressLine1 and beneficiaryAddress.countryCode.

  • MOBILE_MONEY — Mobile-wallet payout (not a bank account).
    Available for KES and TZS only.
    Put the phone number in accountNumber (e.g. +254-712345678) and the
    wallet provider in bankCode / bankName (e.g. M-PESA).

  • HK_BANK — Pay CNY into a Hong Kong bank account
    (bankAddress.countryCode: HK, 3-digit Hong Kong bankCode).
    For HKD domestic payouts use LOCAL, not HK_BANK.

  • STABLECOIN — Crypto wallet payout. Do not send bank fields; send
    cryptoCurrencyWalletAddress, blockchain, cryptoCurrency, and
    cryptoCurrencyWalletHostedOption instead.

Allowed:
string | null
boolean | null

Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets partyType to First_Party when true, Third_Party otherwise. Set true for your own company's accounts (e.g. treasury/OPEX transfers); leave false/omit for third-party payees.

string | null
enum

Relationship of this beneficiary to your company, when your company
has been approved as a nested/downstream client (company category
financial services or crypto).

Required on every beneficiary you create for as long as your
company is approved for downstream/nested use — not just for some
beneficiaries. Send one of:

  • OPEX — Your own operational / operating-expense account
  • NESTED_CUSTOMER — An end-customer of yours
  • NESTED_PAYEE — A payee of your nested customer

Not applicable (omit, or send null) if your company has not been
approved as a nested/downstream client.

Allowed:
documentDetails
array of objects | null

Optional. Supporting documents for this beneficiary.

Use only after the 3-step upload flow on
Upload beneficiary documents:

  1. POST /uploadDocuments → receive items[].link and items[].key
  2. PUT file bytes to items[].link (expires in 15 minutes)
  3. Send { "key": "<items[].key>", "name": "<fileName>" } here

Omit this field, or send [], unless Verto asks for supporting documents.

documentDetails
string | null

Optional. Confirmation of Payee (CoP) / name-check outcome.

Pass this only if you have already called POST /confirm-payee
for this account (mainly UK GBP local payouts) and want that
result stored on the beneficiary. Use the value from the CoP
response (status.detailedStatusIdentifier), for example
MATCH_PERSONAL, CLOSE_MATCH, or NO_ACCOUNT.

Omit if you have not run CoP — update does not require this
field.

string | null
string | null
string | null
string | null
Responses

Updated 13 days ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 13 days ago

Did this page help you?
Privacy policy Terms of service

VertoFX Ltd (No. 10973066) designs and operates the VertoFX website and app. VertoFX is authorised by the Financial Conduct Authority under the Electronic Money Regulations 2011, Firm Reference 901073, for the issuing of electronic money. Database rights protect data on VertoFX website(s) (including pricing data).

Please Note: we do NOT and WILL not deal with unregulated exchanges or affiliates as this currently falls outside of our risk appetite.

© Verto 2026

All rights reserved Registered Office: 20-22 Wenlock Road, London, England, N1 7GU