Create beneficiary

post

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

Create a beneficiary with bank, address, payment-mode, or stablecoin wallet details for payment and FX payout workflows.

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).

paymentMode

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:

accountNumber

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.

accountLabel

string | null

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

cryptoCurrency

string | null

enum

required

Required when paymentMode is stablecoin.

Allowed:

blockchain

string | null

enum

required

Required when paymentMode is stablecoin.

Allowed:

cryptoCurrencyWalletAddress

string | null

required

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

cryptoCurrencyWalletHostedOption

string | null

enum

required

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

country

string | null

bankAddress

object

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

beneficiaryType

string

enum

required

Type of beneficiary. Required.

Allowed:

bankCode

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.

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). 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.

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

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.

currencyId

integer

required

Required. Must reference a supported currency.

forFurtherCredit

object

partyType

string | null

enum

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

Responses

200Successfully created new beneficiary

400unacceptable request

401Unauthorized

404risk factor entry not found

500A server side error occurred