API Reference
FAQSandbox Portal

Create new beneficiary for client

post
https://api-beneficiary-beta.vertofx.com/recipients

Create a new beneficiary account with banking details, address information, and payment preferences

Body Params

If accountLabel is provided, companyName is also required (wallet nickname path). If accountLabel is absent, either companyName or firstName+lastName must be provided, along with a full beneficiaryAddress (addressLine1, city, countryCode, postCode, stateOrProvience).

string
enum
required

Payment method. Required. 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 Mandatory for currencies: USD, GBP, CAD, NOK, SEK, AUD, DKK, CHF, KES, CZK, XAF, TZS.
Allowed:
string | null

Required for all 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 accept +/-, IBAN modes accept spaces/hyphens, SWIFT_STANDARD allows /) is enforced by the runtime validator.

string | null

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

string | null
enum
required

Required when paymentMode is stablecoin.

Allowed:
string | null
enum
required

Required when paymentMode is stablecoin.

Allowed:
string | null
required

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

string | null
enum
required

Required when paymentMode is stablecoin.

Allowed:
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

string | null
string | null
bankAddress
object

Required for non-stablecoin payment modes. countryCode must reference an active supported 2-letter country code.

string
enum
required

Type of beneficiary. Required.

Allowed:
string | null

Required for non-stablecoin payment modes. Trimmed before validation. For GBP local in United Kingdom and other currency-specific modes, format is validated against the configured pattern. SWIFT codes belonging to sanctioned (OORA) countries are rejected.

string | null

Optional alternate national identifier. Trimmed before validation.

string | null

Required for non-stablecoin payment modes.

string | null

Required when beneficiaryType is 'company' (non-stablecoin). For stablecoin, required when accountLabel is provided or when firstName/lastName are not supplied. 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

Conditional requirements are enforced at the root oneOf level:

  • INTERNATIONAL paymentMode: addressLine1 and countryCode required.
  • STABLECOIN without accountLabel: full address (addressLine1, city, countryCode, postCode, stateOrProvience) required. All individual fields (when present) must be up to 35 characters; only alphanumeric characters, spaces, and commas are allowed.
integer
required

Required. Must reference a supported currency.

forFurtherCredit
object
string | null
enum
Allowed:
paymentCapabilities
object | null
boolean | null
string | null
integer | null
string | null
string | null
boolean | null
boolean | null
object

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

documentDetails
array of objects | null
documentDetails
string | null
Responses

Updated 10 days ago

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 10 days ago

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